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

1. Reproduce the issue (e.g. open Hatchery, trigger an action that returns 401).
2. Fetch recent prod logs (if the app is production):

   cd apps/web
   npx convex logs --prod --history 30 --success
   

3. Find the failing function in the output (e.g. [CONVEX A(openclawApi:getRuntimeStatus)] [ERROR] ... 401 'unauthorized').
4. Confirm which deployment is used: logs show the deployment name (e.g. successful-mongoose-647 for prod).
5. Check env vars for that deployment: npx convex env list --prod (or without --prod for dev).
6. 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.