errors & troubleshooting

8 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Authentication failure errors and debugging

Authentication failures return HTTP 401. For LangSmith API-key default, confirm that clients send x-api-key header. For Supabase, confirm that clients send Authorization: Bearer <access_token> header, that project_ref / projectRef matches the Supabase project, and that callers cannot access another user's threads (403).

mda deploy troubleshooting

Common mda deploy issues and fixes: 'project root ... is not a directory' - Pass a directory path to mda dev or mda deploy. 'no agent entry file found' - Add agent.py (Python) or agent.ts/agent.tsx (TypeScript) at the project root. 'mda dev cannot find uv' - Install uv so mda dev can resolve the local LangGraph dev server. 'No LangSmith API key found' - Set LANGSMITH_API_KEY or add it to project .env. 'Deploy fails with 401 or 403' - Confirm the API key belongs to a workspace with beta access. 'Deploy reports a missing model provider API key' - Add the provider key such as OPENAI_API_KEY to .env, export it in your shell, or configure it as a LangSmith workspace secret. 'Deploy reports a Context Hub conflict' - The Context Hub repo changed during deploy. Re-run mda deploy. 'The build exceeds 200 MB' - Remove generated artifacts or large files from the project before deploying. 'Deployment reaches BUILD_FAILED or DEPLOY_FAILED' - Open the printed deployment URL in LangSmith and inspect the revision logs.

Thread authorization security fix GHSA-747p-c922-m55f

Agent Server v0.13.0rc5, v0.12.5, v0.11.3, and v0.10.1+ enforce thread authorization filters during conditional thread creation on the Postgres runtime. Previously, affected versions did not consistently apply custom @auth filters on this path, allowing an authenticated user who knew another user's thread ID to create a run against that thread and observe or modify its conversation state. Only Postgres runtime was affected; in-memory runtime deployments were not affected.

Loopback webhook security fix GHSA-2c9q-c2q9-qgqv

Agent Server v0.10+ blocks loopback webhook targets by default to fix authentication-bypass primitive. webhooks.url.disable_loopback policy defaults to true, blocking relative-URL webhooks (dispatched through in-process ASGI transport bypassing auth) and localhost/127.x/::1/host.docker.internal absolute URLs. Any hostname DNS-resolving into loopback range is blocked, mitigating DNS rebinding. Opt back in by setting webhooks.url.disable_loopback: false in langgraph.json or LANGGRAPH_WEBHOOKS env var, but only when controlling webhook target routes.

Assistant authorization on run creation GHSA-jfj5-wrj9-63x4

Agent Server v0.10+ authorizes attached assistant via assistants.read auth event (matching cron creation) instead of assistants.search, fixing cross-user authorization bypass for deployments with only @auth.on.assistants.read. Breaking changes: (1) @auth.on.assistants.search invoked during run creation is no longer called—ensure @auth.on.assistants.read returns equivalent owner filter; (2) value[metadata] on assistants.read event from run/cron creation is no longer populated—move logic to @auth.on.runs.create_run and @auth.on.crons.create.

agent-server deadlock handling on cancellation

Agent-server v0.2.73 throws a 409 error on deadlock occurrence during run cancellations to handle lock conflicts gracefully.

agent-server TimeoutError logging distinction

Agent-server v0.2.70 improved error handling to better distinguish and log TimeoutErrors caused by users from internal run timeouts.

agent-server CancelledError handling in workers

Agent-server v0.2.51 handled CancelledError by marking tasks as ready to retry, improving error management in worker processes.

Give your agent this brain