Skip to main content
This page lists the failures you’re most likely to hit when shipping a Reminix agent or tool. Each entry has the symptom, the cause, and the fix. If you don’t see your problem here, every error response includes an execution.url pointing at the dashboard. Open it for full input/output and stack traces.

​
Deploy fails

​
”No entrypoint found”

Symptom: the deploy log says it couldn’t find an entrypoint and the build is marked failed. Cause: Reminix only looks for specific filenames at the project root. Fix: rename your file to one of these:
LanguageAllowed entrypoints (in order)
TypeScript / JavaScriptserver.ts, agent.ts, index.ts (or .js)
Pythonserver.py, agent.py, main.py
If your code lives in a subfolder of a monorepo, set the folder when connecting the repo or pass -d <path> to reminix deploy.

​
”Container exited immediately”

Symptom: the build succeeds but the container shuts down within seconds and the agent never becomes reachable. Cause: your entrypoint runs to completion without calling serve(). Once the script returns, the process ends. Fix: make sure serve(...) is the last (or top-level) call in your entrypoint, with at least one agent or tool registered. 
# server.py — wrong: handler is defined but serve() is missing
@agent
async def hello(prompt: str) -> str:
    return f"Hello! {prompt}"

# server.py — right
@agent
async def hello(prompt: str) -> str:
    return f"Hello! {prompt}"

serve(agents=[hello])

​
Agent unreachable inside the container

Symptom: deploy succeeds, status is “live”, but every invocation returns 502. Cause: the server is listening on localhost / 127.0.0.1, which is unreachable from outside the container. Fix: use the default serve() host. Don’t override host/hostname to localhost. Reminix routes traffic to 0.0.0.0 on the configured PORT.

​
Runtime fails

​
”Secret not found at runtime”

Symptom: the handler throws KeyError: 'OPENAI_API_KEY' (Python) or Cannot read properties of undefined reading process.env.OPENAI_API_KEY (TypeScript). Cause: the secret hasn’t been set on the project, or you’re reading the wrong name. Fix: 
reminix secret list                        # check what's set
reminix secret set OPENAI_API_KEY sk-...   # add or update
reminix deploy                             # restart the container so it picks up the new value
Names are case-sensitive. Openai_Api_Key and OPENAI_API_KEY are different secrets. See Configuration & Secrets for the full reference.

​
Agent times out (504 TimeoutError)

Symptom: invocation returns 504 Gateway Timeout after roughly the project’s configured timeout. Cause: your handler is taking too long. The most common reasons:
  • A slow upstream API (model provider, database) without a timeout configured on your side
  • A retry loop that doesn’t bound itself
  • Synchronous I/O that’s blocking the event loop in an async handler
Fix:
  • Stream the response. Convert your handler to an async generator and yield as soon as data is available — clients see output without waiting for the full response. See Streaming.
  • Set timeouts on your upstream calls. Don’t rely on defaults.
  • For genuinely long jobs, use a Workflow and resume in steps instead of one long invocation.

​
Agent throws an unhandled error (502 ExecutionError)

Symptom: invocation returns 502 Bad Gateway with error.type: "ExecutionError". Cause: your handler raised an exception the runtime didn’t expect. Fix: open the execution.url in the response. The dashboard shows the input that caused it, the stack trace, and the duration. Reproduce locally with the same input, then either fix the bug or wrap the failing call in a try/except and return a sanitized error so users don’t see your stack traces. 
@agent
async def writer(prompt: str) -> str:
    try:
        return await call_model(prompt)
    except RateLimitError:
        return "I'm rate-limited right now — try again in a minute."

​
Validation error (400 ValidationError)

Symptom: every call returns 400 with a message like Input field 'prompt' is required. Cause: the request body doesn’t match the agent’s input schema. Either the caller is wrong or the schema isn’t what you think it is. Fix:
  • Confirm the agent type. A prompt agent expects { "input": { "prompt": "..." } }. A chat agent expects { "input": { "messages": [...] } }. See Agents.
  • If you defined a custom schema (Zod or Pydantic), check that the field names and types match the request.
  • The dashboard’s execution log shows the exact input the runtime received.

​
MCP tools

​
MCP client can’t reach the server

Symptom: Claude Desktop / Cursor / Windsurf shows the Reminix server as failed or “no tools available”. Cause: usually one of:
  1. The Authorization header is missing or wrong
  2. The client is reaching https://api.reminix.com/mcp but the server is misconfigured
Fix:
  • Verify the token works against the REST API: 
    curl https://api.reminix.com/v1/agents \
  -H "Authorization: Bearer reminix_sk_..."
    If this returns 401, your token is invalid — issue a new one from the dashboard.
  • Check the MCP config matches the format in Connecting an MCP client. The header must be Authorization: Bearer <token>, not just <token>.
  • Restart the MCP client after editing its config. None of the popular clients pick up changes hot.

​
Tools don’t appear in the client

Symptom: the MCP server connects but no tools show up. Cause: the project has no tools deployed, or you’re authenticated to the wrong project. Fix: 
reminix tool list           # what does the project actually have?
If the list is empty, your code isn’t passing tools to serve(). If the list is populated, check whether your token is scoped to a different project — Personal Access Tokens need an X-Project header to choose one.

​
Invocations

​
404 Not Found invoking an agent

Symptom: you call POST /v1/agents/my-agent/invoke and get 404. Cause: one of:
  1. The agent name doesn’t match what’s registered. The name is the string passed to agent("my-agent", ...) (TypeScript) or name="my-agent" (Python), or the function name if name is omitted in Python.
  2. The deploy succeeded but discovery missed the agent — usually because the entrypoint never reached the serve() call.
Fix: 
reminix agent list          # what's actually registered?
reminix deploy status       # did the latest deploy succeed?

​
401 AuthenticationError

Symptom: every request returns 401. Cause: the Authorization header is missing, malformed, or the token is invalid. Fix:
  • Format must be Authorization: Bearer reminix_sk_... — the Bearer prefix is required.
  • Project API keys (reminix_sk_) only work for the project they were issued for.
  • Personal Access Tokens (reminix_pat_) require an X-Project header naming the target project. See Authentication.

​
429 RateLimitError

Symptom: intermittent 429 responses under load. Cause: you’ve exceeded your project’s rate limit. Fix: add exponential backoff in your client code. The SDK does not retry automatically — see the retry pattern in TypeScript Error Handling or Python Error Handling.

​
Streaming

​
Stream connection drops mid-response

Symptom: an SSE stream cuts off before [DONE]. Cause: an intermediate proxy (corporate firewall, CDN, ngrok free tier) closed an idle connection, or the agent itself raised an exception. Fix:
  • Check the execution.url for the run. If the agent threw, the dashboard shows it.
  • If the agent finished cleanly but the stream closed early, the issue is on the network path, not Reminix. Test from a different network or use the Try it panel on the agent’s detail page in the dashboard.
  • Handle stream errors in your client — every stream may emit an error event before closing. See Streaming → Error handling.

​
Workflows

​
Paused workflow expired

Symptom: trying to resume a workflow returns “run not found” or “run failed”. Cause: workflow runs have a maximum lifetime. If a paused workflow isn’t resumed in time, it’s marked failed and the run is no longer resumable. Fix: check the lifetime in your project settings. For approval flows that may sit idle for hours or days, set a longer timeout. For ephemeral interactive flows, the default is fine — make sure your client stores the run_id and resumes promptly.

​
Still stuck?

  • Open the failed execution in the dashboard via the execution.url in the response. The full input, output, logs, and timing are there.
  • Tail the deploy logs with reminix deploy status <id>.
  • Reach out via the support email with the execution ID — that’s enough for us to find the run.

​
Next steps

Errors

The error response shape and full status code reference.

Configuration & Secrets

How env vars and secrets work end-to-end.

Deploy from GitHub

The deploy flow from connect to live.

CLI Reference

The commands referenced throughout this page.