SkyState

Troubleshooting ​

CLI Errors ​

Missing required option: --env ​

sky state public push and sky state public show require an environment. There is no default environment unless you set one in your CLI config. These commands also require --project <slug>.

bash
# Fix: provide the environment
sky state public push --project my-app --file config.json --env development
sky state public show --project my-app --env production

To set a default environment so you don't have to pass it every time:

bash
sky config set default_env development

Valid environments: development (alias dev), staging (alias stg), production (alias prod).

sky onboarding shows a stack picker instead of writing files ​

sky onboarding no longer writes .env.local or re-runs a repo initialization flow. It is an interactive wizard that helps you pick a project and a starter path.

If you need a fresh API key, create one with:

bash
sky project keys create --project my-app

Conflict: environment was updated while editing. ​

Two concurrent pushes wrote to the same environment at the same time. Pull the latest public state, merge your changes, and push again:

bash
sky state public show --project my-app --env staging
# review the current state, update your local file
sky state public push --project my-app --file config.json --env staging

Non-interactive mode: breaking changes require --yes to confirm. ​

In CI or piped environments, sky state public push refuses to proceed when it detects breaking changes (key removals or type changes) without explicit confirmation. Pass --yes to confirm:

bash
sky state public push --project my-app --file config.json --env production --yes

Error: Not logged in. / No session stored ​

Run sky login to authenticate. For CI or other non-interactive use, set SKYSTATE_API_KEY to a project API key created via sky project keys create:

bash
# In CI (GitHub Actions, etc.)
SKYSTATE_API_KEY=${{ secrets.SKYSTATE_API_KEY }} sky state public push --project my-app --file config.json --env staging --yes

The CLI reads SKYSTATE_API_KEY automatically - no sky login step is needed when this variable is set.

Project "..." not found. ​

The slug passed to --project or sky project show does not match any project in your account. List your projects to find the correct slug:

bash
sky project list

SDK Errors ​

[SkyState] Missing required configuration ​

One or more required fields were not provided to SkyStateProvider or createSkyStateClient().

Missing provider props ​

SkyStateProvider always requires account and project as props. They are not read from environment variables. The environment prop defaults to "development" when omitted from SkyStateProvider; when constructing a core client directly, environment is required.

tsx
<SkyStateProvider
  account="acc_example"
  project="my-app"
  environment="development"
>
  <App />
</SkyStateProvider>

Ensure account and project are not empty strings.

usePublicState/useUserState/useAuth must be used within a <SkyStateProvider> ​

This error is thrown when a React SDK hook is called outside of a <SkyStateProvider> tree. Wrap the component (or your entire app) in <SkyStateProvider>:

tsx
// Before (broken)
function MyComponent() {
  const { value } = usePublicState('feature', { enabled: false });
  return <div>{String(value.enabled)}</div>;
}

// After (correct)
function App() {
  return (
    <SkyStateProvider account="acc_example" project="my-app">
      <MyComponent />
    </SkyStateProvider>
  );
}

Config not updating after a push ​

Config responses are cached by the server. After a push to production, clients may serve the previous version for up to 15 minutes. For development and staging, the maximum delay is 10 seconds.

If you need the latest value immediately in a browser app, wait for the cache TTL to expire or remount the SDK client after the TTL has passed.

Temporary sign-in renewal issues ​

Temporary sign-in renewal issues do not immediately force users to sign in again. The auth snapshot can stay authenticated with an advisory error field while the SDK recovers.

This means a transient provider outage or network interruption does not have to interrupt the user's current screen. If your UI surfaces repeated onError events as toasts, throttle them on the consumer side.

When the session is expired or invalid, auth transitions to unauthenticated and the user can sign in again.

User state authorization failure ​

A user-state authorization error means the signed-in user cannot access the configured project or environment.

Check:

  • The account and project props on SkyStateProvider point to the correct project.
  • The end-user's Firebase token is for the correct Firebase project (developer vs end-user Firebase projects are separate).
  • The project's end-user auth settings allow the user's identity provider.

After fixing the configuration, refresh the affected screen or retry the user action.

Session lost after page reload (storage write failure) ​

If onError fires with err.code === 'storage_write_failed', the token storage adapter could not persist the session. The active tab continues to work using the in-memory session, but a page reload or new tab will start unauthenticated.

Common causes:

  • localStorage is blocked (private browsing mode in some browsers, quota exceeded, or security settings).
  • A custom AuthTokenStorage adapter's set() method threw.

The SDK emits this error once at the point of failure and does not repeat it. To surface it to users:

tsx
<SkyStateProvider
  onError={(err) => {
    if (err.code === 'storage_write_failed') {
      showBanner('Your session will not persist after reload.');
    }
  }}
>
  <App />
</SkyStateProvider>

If you are in private browsing mode and want sessions to persist, use a custom AuthTokenStorage adapter backed by sessionStorage or another mechanism available in that context.

Still stuck? ​

Contact support at support@skystate.io.