Fix common Maple Proxy problems, including 401, 400, 403, 404, 502 and 504 errors, connection refused, slow first requests, timeouts and browser CORS issues.

Start by turning on debug logs: MAPLE_DEBUG=true (or -d). The proxy logs each request’s method and path, never the API key.

Error responses

401: “No API key provided”

The request had no usable key. Either:

send Authorization: Bearer <your key> (exactly Bearer , then the key), or
set MAPLE_API_KEY for trusted, non-browser clients.

If MAPLE_API_KEY is set and you still get this, CORS is probably on. In CORS mode the saved key is ignored, and the Docker image turns CORS on by default. Send a key with every request, or set MAPLE_ENABLE_CORS=false for a private deployment.

401 from Maple

The key reached Maple but was rejected. It may be mistyped, deleted, or from a different account. Create a new key and try again.

400

Usually an old or unknown model ID. Call /v1/models and use an ID from that list exactly.

403 (desktop app)

With CORS off, the desktop app’s Local Proxy rejects requests that come from a web browser. Use a local process instead, or turn on Enable CORS for browser clients and send a key with every request.

404

The proxy only forwards /v1/chat/completions, /v1/embeddings and /v1/models. Check the path, and check whether your tool expects the base URL with or without /v1.

502: “Failed to communicate securely with the Maple backend”

The proxy couldn’t verify the enclave or reach the backend. Check:

MAPLE_BACKEND_URL is right. For production, leave it at https://enclave.trymaple.ai.
MAPLE_PCR0_ENVIRONMENT matches the backend: production for production, development only for the development enclave.
The machine can reach the backend over HTTPS.

The proxy retries the enclave check on the next request, so you don’t need to restart it after fixing the network.

504

The backend didn’t start responding within MAPLE_REQUEST_TIMEOUT_SECS. Large prompts and slow models can need more time. Raise the timeout, or use streaming. See timeouts.

5xx passed through from Maple

Other server errors come from Maple’s backend or the model provider, and can be temporary outages even when your setup is right. Check Maple’s status page.

Connection problems

Connection refused

Make sure the proxy is running: curl http://127.0.0.1:8080/health.
Check the host and port. The proxy listens on 127.0.0.1:8080 by default.
Use 127.0.0.1, not localhost. The proxy listens on IPv4 only, and some clients try IPv6 (::1) first for localhost.
In Docker, publish the port (-p 127.0.0.1:8080:8080).
If you used the desktop app, Maple must stay open.

The proxy won’t start

Invalid socket address: MAPLE_HOST must be a numeric IP address such as 127.0.0.1 or 0.0.0.0, not a hostname.
Port already in use: another program, or the desktop app’s Local Proxy, is on that port. Pick another with --port.
cache namespace root must be canonical padded base64…: regenerate the value with openssl rand -base64 32.

The first request is slow

The proxy verifies the enclave and opens its encrypted session on the first /v1 request, not at startup. Later requests reuse that session.

A stream stops partway

If no chunk arrives within MAPLE_STREAM_IDLE_TIMEOUT_SECS, the proxy ends the stream with an error. Raise the idle timeout for models that think for a long time before answering.

Browser apps

A web page can only call the proxy if CORS is on (MAPLE_ENABLE_CORS=true). Then every request must send its own key, and the browser must be allowed to send the Authorization header; the proxy allows any requested headers in CORS mode.

Don’t expose a proxy with a saved key to the browser. See authentication.

Still stuck?

Open an issue in the Maple repository with the proxy version (maple-proxy --version) and the debug logs. Remove any secrets first.

Troubleshooting