playbooks

home / skills / openagentsinc / openagents / convex-logs

convex-logs skill

/.skills/convex-logs

This skill streams and analyzes Convex deployment logs to diagnose errors, verify deployments, and correlate env vars with API responses.

npx playbooks add skill openagentsinc/openagents --skill convex-logs

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
5.1 KB
---
name: convex-logs
description: Check and stream Convex deployment logs from the CLI. Use when debugging Convex actions, 401/500 errors, failed queries or mutations, or when you need to see what functions ran and their output.
---

# 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

1. **Reproduce the issue** (e.g. open Hatchery, trigger an action that returns 401).
2. **Fetch recent prod logs** (if the app is production):
   ```bash
   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.

Overview

This skill checks and streams Convex deployment logs from the CLI to help you debug failed actions, validation errors, 401/500 responses, and timing information for queries, mutations, and actions. It lets you target dev or prod deployments, fetch recent history, and inspect deployment environment variables so you can correlate code, secrets, and runtime behavior. Use it directly from the app folder that contains the convex/ directory.

How this skill works

The skill runs convext CLI commands (npx convex logs / env) to stream log lines or fetch a history snapshot from the selected deployment. It shows which functions executed, their duration, and error messages. You can switch between dev (default) and prod with --prod, include successful runs, output raw JSONL, or target a specific deployment name. Env commands list or retrieve values set in the Convex deployment rather than local .env files.

When to use it

  • Investigating user-reported errors from Convex actions (e.g. unauthorized, ArgumentValidationError, timeouts).
  • Confirming which Convex deployment (dev vs prod) your app is using when behavior differs between environments.
  • Seeing recent function executions, success/failure status, and execution durations for queries, mutations, and actions.
  • Debugging missing or mismatched env vars (OA_INTERNAL_KEY, PUBLIC_API_URL) that cause 401s with external APIs.
  • Fetching a finite set of recent entries instead of streaming when network or timeout issues occur.

Best practices

  • Run commands from the app directory that contains convex/ (monorepos commonly use apps/web).
  • Remember dev is the default; add --prod for production logs and env checks.
  • Use --history N to fetch a finite number of entries and avoid streaming timeouts.
  • Include --success when you need successful runs (defaults may show failures only).
  • Use --deployment-name to target a specific deployment instance when multiple exist.

Example use cases

  • Stream production logs to find a failing action returning 401: npx convex logs --prod --history 30 --success.
  • Verify deployment env vars: npx convex env list --prod and npx convex env get OA_INTERNAL_KEY --prod.
  • Quick snapshot of recent activity: npx convex logs --history 50 to inspect recent function timings and errors.
  • Target a named deployment: npx convex logs --deployment-name dev:effervescent-anteater-82.
  • Output raw log events for automated parsing: npx convex logs --jsonl --history 100.

FAQ

Why do Convex actions not see my .env.local values?

Convex actions only read env vars set in the Convex deployment. Use npx convex env list/get to inspect deployment vars and npx convex env set to configure them.

I see no logs or the wrong deployment—what next?

By default logs target dev. Add --prod for production. If still wrong, confirm you are in the correct app folder and that the project is linked and you are logged in (npx convex dashboard to verify).

How do I avoid streaming timeouts when debugging?

Use --history N to fetch a fixed number of recent entries and exit instead of streaming.