Troubleshooting - UnitBuilds-CC/V.E.L.O.C.I.T.Y.-MCP GitHub Wiki

Troubleshooting

Common Issues

"File path must be absolute"

Provide the full absolute path. Both Windows (C:\Users\...) and Unix (/home/...) paths are supported.

"File path contains traversal sequence '..'"

Use absolute paths without .. directory traversal.

Shared memory: server not responding

Delete the buffer file and restart both processes. The state machine may be stuck.

HTTP: Connection refused

Start with --mode http --addr 0.0.0.0:3000 and check the port isn't in use.

HTTP: 401 Unauthorized

Include Authorization: Bearer <key> header if API key auth is enabled.

HTTP: 413 Payload Too Large

Request exceeds max_request_size (default: 1 MB). Reduce size or increase limit in config.

"Rate limit exceeded"

Default: 20 req/sec, burst 100. Throttle requests or increase limit in config.

"Sandbox violation"

Expected security behavior. Check audit log for details. The tool attempted a disallowed operation.

Build: slow release builds

Normal — lto = true + codegen-units = 1 is slow. Use cargo check for development.

Build: linker not found (Windows)

Install Visual Studio Build Tools with C++ workload.

FAQ

Q: What MCP protocol version? A: 2024-11-05. Supports ping, logging/setLevel, notifications/cancelled, cursor pagination, elicitation, roots.

Q: Multiple clients simultaneously? A: Stdio: one client per process. HTTP: up to 1000 concurrent sessions. Shmem: one host at a time.

Q: Linux/macOS compatible? A: Yes. Fully cross-platform. Linux gets seccomp sandboxing. Path validation works on all platforms.

Q: All NDA operations native Rust? A: Yes. Since v3.0, all NDA compile/read/execute run natively. C# engine is optional.

Q: How to monitor in production? A: Prometheus at /metrics, Grafana dashboard in monitoring/, OpenTelemetry with observability feature.

Q: How to add custom tools? A: Three ways: #[mcp_tool] proc macro, plugin marketplace, or add to src/registry.rs.

Q: Maximum file size? A: Built-in tools: limited by memory. External tools: server passes path without reading file.

See also: Getting-Started, Configuration, Security-Model

⚠️ **GitHub.com Fallback** ⚠️