Guides

Troubleshooting

Debug publish, activation, runtime, job, webhook, secret, and rollback failures.

For agents: Start with publish output, activation status, missing secrets, release resources, and owner-visible app events.

Checks

Confirm USERLAND_API_KEY is set only in the local environment.
Validate manifest.userland.json.
Check activation status for pending_secrets or requires_migration.
Read app events with npm run userland -- apps events "$APP_ID" --severity error.
Roll back only to a compatible retained release.

First Commands

npm run userland -- apps events "$APP_ID" --limit 25
npm run userland -- apps releases "$APP_ID"
npm run userland -- apps secrets set "$APP_ID" SECRET_NAME --value "$VALUE"
npm run userland -- apps rollback "$APP_ID" "$RELEASE_ID"

Publish failures

invalid_bundle: every release needs a non-empty files array. When using the CLI, confirm the app directory is not empty.
invalid_path: release paths must be relative, must not contain .., and must not publish under _userland/.
missing_static_root: runtime.static_root must contain at least one release file.
missing_server_entry: runtime.server_entry must point to a file in the release.
bundle_too_large: v0 accepts up to 1000 files, 20 MiB per file, and 100 MiB total decoded bytes.

Activation failures

pending_secrets means the release is stored but not live. Set each missing secret:

printf '%s' "$VALUE" | npm run userland -- apps secrets set "$APP_ID" SECRET_NAME

requires_migration means the release changes durable resources in a way v0 will not apply automatically. Use an add/backfill/hide approach: add a new resource name, backfill in runtime code or an admin path, then stop using the old resource.

Runtime failures

Read recent error events:

npm run userland -- apps events "$APP_ID" --severity error --limit 25

Check that dynamic routes are reachable only when fallback is server, that the server module exports fetch, and that frontend code calls your app origin rather than the control-plane API.

Job and Webhook Failures

Check events for the job or webhook name, then compare the manifest with server/index.js:

npm run userland -- apps events "$APP_ID" --type job --limit 25
npm run userland -- apps events "$APP_ID" --type webhook --limit 25

Job names must match exactly. Webhooks that deliver to jobs must reference a declared job and a required secret that has been set for the app.