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 account-visible app events.

Checks

Confirm USERLAND_API_KEY is set only in the local environment, or run userland auth status to verify saved CLI credentials and selected account.
Confirm the selected platform account when publishing or listing team/client apps.
Validate manifest.userland.json.
Check activation status for pending_secrets or requires_migration.
Read app events with userland apps events "$APP_ID" --severity error.
Roll back only to a compatible retained release.

If a team/client app is missing from apps list, run userland accounts list and check whether USERLAND_ACCOUNT_ID, --account, or a saved account_id is selecting a different account.

If you need help from Userland, run userland support open --subject "..." --message "..." --app "$APP_ID" or open Support in the console. The support request includes account context and prints a correlation_id for follow-up.

403 on CLI/API operations means the authenticated actor belongs to the app’s platform account but their account role cannot perform the operation. App-user roles such as admin or editor only apply inside the published app runtime. 404 can mean the actor is not a member of the app’s owning account.

402 means the selected account is allowed to make the request, but its plan does not include the feature or limit. Check error.details.violations for manifest paths such as /app/visibility, /resources/jobs/*/schedule, or /resources/webhooks/*/provider.

Auth and CLI Credentials

Userland platform auth is passwordless. The console signs in with email links, the CLI signs in with browser-approved device authorization, and app/API operations use API keys. There is no platform password reset flow.

Email link expired or invalid: request a new console signin link. Links are short-lived and single-use, and /login/confirm consumes them only after the explicit browser continue action.
Device authorization pending: open the printed verification URL, complete email signin/signup in the browser if needed, then approve the CLI on /device.
Device denied or expired: run userland login again to start a fresh device flow.
Device poll returned slow_down: wait for the returned interval before polling again. Repeated fast polls will keep slowing down.
Device consumed: the API key was already returned once. Run userland login again if credentials were not saved.
API key revoked or invalid: unset stale USERLAND_API_KEY, remove saved credentials with userland auth logout, then run userland login or save a known-good key with userland auth save-key --api-key ....
Missing saved credentials: run userland auth status, confirm USERLAND_API_KEY is set or ~/.userland/credentials.json exists, then sign in with userland login.

Legacy password endpoints intentionally return 410 with password_auth_disabled or password_signup_disabled. Do not use /v0/auth/token, /v0/platform/sessions, password reset request/confirm, or unauthenticated POST /v0/accounts for launch auth.

First Commands

userland apps events "$APP_ID" --limit 25
userland apps releases "$APP_ID"
userland apps secrets set "$APP_ID" SECRET_NAME --value "$VALUE"
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 5000 files, 20 MiB per file, and 500 MiB total decoded bytes.
entitlement_required or plan_limit_exceeded: remove the paid-only manifest feature, reduce the declared resource count, select the correct account, or upgrade/comp the account.

Activation failures

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

printf '%s' "$VALUE" | 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:

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:

userland apps events "$APP_ID" --type job --limit 25
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.