Troubleshooting

Common errors when building Vincia plugins, plus migration notes for breaking SDK changes.

"Outbound scope denied"

You called ctx.outbound.fetch to a host you didn't declare in manifest.scopes_required. The sandbox blocks the call.

Fix: add the host (e.g. outbound.fetch:api.example.com) to your manifest. Submit a fresh version; reviewers verify the scope is necessary.

"CPU cap exceeded"

A single invocation ran longer than your declared resource_budget.cpu_ms. The sidecar killed the isolate.

Fix: profile your handler, raise the cap in the manifest (and justify it in the submission notes), or split the work across multiple invocations using ctx.queue.enqueue.

"Secret not found"

You called ctx.secrets.get('api_key') but the user hasn't configured it for this build.

Fix: surface a friendly error to the caller; document required secrets in the listing description. The Studio UI prompts users for missing secrets at install time when they're declared in the manifest.

"Manifest validation failed"

Your manifest.json doesn't match the v1 schema.

Fix: run vincia validate locally — it prints the exact JSON-pointer of the offending field. The full schema lives in @vincia/sdk-types.

Migration: SDK 0.1 → 0.2

(Placeholder for the first breaking change. The SDK contract is frozen at v1.0; breaking changes are rare and always accompanied by a migration script.)