Rayfin

Deployment troubleshooting

Fix common rayfin up, capacity, static hosting, and deployment-target errors using exact CLI messages.

Match the exact error text from the CLI, then apply the fix. Re-run with --verbose when a Fabric request needs more detail.

Authentication and keychain errors

Error textFix
Deployment fails with 401 or 403Run npx rayfin login, then retry.
OS keychain or credential-storage failureUse npx rayfin login --encryption-fallback-enabled only for a development environment without keychain support.
RAYFIN_TOKEN could not be decoded as a JWT, so its audience cannot be verified.Use a token for the expected Fabric audience, or unset RAYFIN_TOKEN and run rayfin login.

Workspace and capacity errors

Error textFix
The Fabric capacity assigned to this workspace is exhausted and cannot create another Rayfin item.Pass a workspace with available capacity using --workspace-id <id>, or pass --capacity-id <id>.
--capacity-id must be a GUID.Copy the Fabric capacity GUID from the Fabric portal.
--workspace-id and --capacity-id cannot be used together.Remove one option so Rayfin resolves either the workspace or the capacity.
RAYFIN_WORKSPACE_ID and --capacity-id cannot be used together.Unset RAYFIN_WORKSPACE_ID or remove --capacity-id.
No workspace targeting context. Pass --workspace <name> (or --workspace-id <id> / --workspace-uri <url>), or run \rayfin up` once interactively to record a deployment.`Provide a workspace target for non-interactive deployment.
Multiple premium Fabric capacities are available and require interactive selection.Run interactively or pass --capacity-id <id>.
Provisioning and assigning Fabric trial capacity to workspaceRun with --yes, pass --capacity-id, or ask an admin to assign existing capacity.
Workspace Admin permission is required to assign capacity toAsk a workspace Admin to assign capacity or promote your role.
Fabric trials are disabled for this tenant.Ask the tenant admin to enable trials or deploy to a workspace that already has capacity.
Fabric did not finish the workspace capacity assignment withinWait for Fabric assignment to finish, then retry.

Item and deployment-target errors

Error textFix
Pass a non-empty value with --item-name <name>.Provide a non-empty item display name or omit the flag.
Omit --item-name to redeploy the existing item, or deploy to a different workspace.A recorded deployment already targets an item; omit --item-name unless creating a new target.
No remote endpoint configured.Run npx rayfin up first so static-only and connector commands have a deployed target.
This deployment has no recorded API URL, so the deployed transport has no endpoint to call.Run npx rayfin up to refresh deployment metadata.
This deployment has no recorded publishable key, which the deployed route requires.Run npx rayfin up to refresh deployment metadata.

Static hosting errors

Error textFix
Compressed package size (...) exceeds the 100 MB limit.Exclude large assets or source maps, then redeploy static content.
Static hosting is enabled but services.staticHosting.assetAccess is not set in rayfin.ymlAdd assetAccess: protected or assetAccess: public. Non-interactive rayfin up defaults a missing posture to protected and writes it to rayfin.yml. New in 1.35.1
services.staticHosting.assetAccess in rayfin.yml must be protected or publicFix the value or the environment variable that resolves it.
Static hosting requires an explicit access posture. Set 'services.staticHosting.assetAccess' to 'protected' to require Fabric sign-in or 'public' to serve anyone with the link, then deploy again.Add the access posture and redeploy.
Invalid static hosting posture: 'services.staticHosting.embedded.only: true' cannot be combined with 'services.staticHosting.assetAccess: public' because an embedded app has no standalone surface to make public.Use assetAccess: protected or set embedded.only: false.
The static-hosting access posture has not been recorded. Run 'rayfin up' to record 'services.staticHosting.assetAccess' before trying again.Run a full deploy with a current CLI.

Schema and runtime errors

Error textFix
Dialect is required when Data module is enabledSet services.data.dialect: mssql in rayfin.yml.
Destructive schema change warningReview operations and use --force only when the data loss is expected.
GraphQL Internal server error after deployAdd explicit max values to every @text() field, then apply the schema.
PromptDiagnose a failed Rayfin deployment
Use the exact error text from my failed `npx rayfin up` or `npx rayfin up status` run to fix the deployment. Re-run with `--verbose` if needed. Check workspace targeting, capacity readiness, `services.staticHosting.assetAccess`, static archive size, and schema configuration. Do not pass `--force` unless the destructive schema operations are expected.

Source-oriented notes for agents

The CLI error strings above come from the 1.36.2 package files dist/errors.js, dist/commands/capacity-options.js, dist/workflows/fabric-readiness/steps/*.js, dist/workflows/up/steps/ensure-static-hosting-posture.js, and dist/services/runtime-settings/errors.js.

Something wrong on this page?Report an issueEdit this page

On this page