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

bash

# 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:

bash

# 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):

bash

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.

convex-logs

NPX Install

Tags

SKILL.md Content

Check Convex logs

When to use this skill

Prerequisites

Default deployment: dev vs prod

Commands

Stream or fetch logs

Log command options

Inspect environment variables

Typical workflow

Example log output

Troubleshooting