Check Convex logs

Use this skill when you need to inspect what is happening in a Convex deployment: failed actions, validation errors, 401 unauthorized from external APIs, or which functions ran and how long they took.

When to use this skill

• User reports an error from Convex (e.g. "unauthorized", "ArgumentValidationError", action timeout).

• You need to confirm which Convex deployment (dev vs prod) is being used.

• You need to see recent function executions (queries, mutations, actions) and their success/failure.

• You are debugging Convex env vars (e.g. OA_INTERNAL_KEY, PUBLIC_API_URL) and want to correlate with API responses in logs.

Prerequisites

• The project must use Convex and have npx convex (or convex CLI) available.

• Run Convex commands from the app directory that contains the convex/ folder (e.g. apps/web in a monorepo).

• You must be logged in and have the correct Convex project linked (npx convex dashboard to verify).

Default deployment: dev vs prod

Important: By default, convex logs and convex env target the dev deployment. For production issues (e.g. openagents.com), you must pass --prod .

• Dev (default): npx convex logs streams from the project's dev deployment.

• Prod: npx convex logs --prod streams from the project's production deployment.

Same for env vars: npx convex env list shows dev; npx convex env list --prod shows production.

Commands

Stream or fetch logs

From the app that has convex/ (e.g. apps/web)

cd apps/web

Stream logs (default: dev). Use Ctrl+C to stop.

npx convex logs

Stream production logs

npx convex logs --prod

Show last N log entries then exit (no streaming). Good for quick checks.

npx convex logs --prod --history 30

Include successful executions (default is failures only in some contexts)

npx convex logs --prod --history 25 --success

Log command options

Option Meaning

--prod

Use the production deployment (required for prod debugging).

--history [n]

Show the last n log entries; then exit instead of streaming.

--success

Include successful function runs in the output.

--jsonl

Output raw log events as JSONL.

--deployment-name <name>

Target a specific deployment (e.g. dev:effervescent-anteater-82 ).

--env-file <path>

Use env file for CONVEX_DEPLOYMENT or similar.

Inspect environment variables

Convex actions do not read .env.local . They only see variables set in the Convex deployment (Dashboard or CLI). To see what the deployment has:

List env vars on dev (default)

npx convex env list

List env vars on production

npx convex env list --prod

Get a single variable (e.g. confirm OA_INTERNAL_KEY is set; value is hidden in output)

npx convex env get OA_INTERNAL_KEY --prod

Use this to confirm that keys and URLs (e.g. OA_INTERNAL_KEY , PUBLIC_API_URL ) are set on the deployment that's actually serving the app.

Typical workflow

• Reproduce the issue (e.g. open Hatchery, trigger an action that returns 401).

• Fetch recent prod logs (if the app is production): cd apps/web npx convex logs --prod --history 30 --success

• Find the failing function in the output (e.g. [CONVEX A(openclawApi:getRuntimeStatus)] [ERROR] ... 401 'unauthorized' ).

• Confirm which deployment is used: logs show the deployment name (e.g. successful-mongoose-647 for prod).

• Check env vars for that deployment: npx convex env list --prod (or without --prod for dev).

• Fix env in Convex (Dashboard or npx convex env set ... ) or fix the calling code; redeploy if needed.

Example log output

Watching logs for production deployment successful-mongoose-647... 2/4/2026, 12:39:06 PM [CONVEX A(openclawApi:getInstance)] Function executed in 434 ms 2/4/2026, 12:39:06 PM [CONVEX A(openclawApi:getRuntimeStatus)] [ERROR] '[openclawApi getRuntimeStatus] API error response:' 401 'unauthorized' 2/4/2026, 12:39:06 PM [CONVEX A(openclawApi:getRuntimeStatus)] Uncaught Error: unauthorized ...

Here, getInstance succeeded but getRuntimeStatus got 401 from the external API—often a mismatch of OA_INTERNAL_KEY between Convex and the API worker.

Troubleshooting

• "No logs" or wrong deployment: Use --prod when the live app uses the production Convex deployment.

• 401 from Convex actions calling an API: Set OA_INTERNAL_KEY (and PUBLIC_API_URL if needed) in the same Convex deployment that runs the action (npx convex env set OA_INTERNAL_KEY "..." --prod ), and ensure the API worker has the same key (e.g. npx wrangler secret put OA_INTERNAL_KEY in the API app).

• Timeout when streaming: Use --history N to fetch a finite number of entries and exit instead of streaming.

• Need a specific deployment: Use --deployment-name <name> (e.g. dev:effervescent-anteater-82 ) for that deployment's logs.