mastra-ai/mastra · error

The active sandbox provider does not support runtime GitHub

Error message

The active sandbox provider does not support runtime GitHub token refresh.

What it means

The GithubTokenRegistration.inject callback needs to swap the sandbox's GH_TOKEN at runtime when the GitHub CLI token is refreshed. If the resolved sandbox provider instance does not implement setEnv, setupHook throws because token refresh is impossible with that provider.

Source

Thrown at mastracode/factory/src/workspace.ts:350

      }
      const target: SessionSandbox = requireExec(args.sandbox);
      // The `gh` CLI needs a PAT when the org configured one (installation
      // tokens 403 on integration-restricted endpoints); git clone/checkout
      // keep using the minted installation token. Resolved per start so the
      // installed credential never outlives rotation.
      const patKind = await resolveGithubPatKind('default');
      const ghCliToken =
        (await getGithubPat(() => github.integrationStorage, session.orgId, patKind)) ?? (await getRepositoryToken());
      target.setEnv?.(env => ({ ...env, GH_TOKEN: ghCliToken }));
      // Observability only — nothing reads these columns for decisions. The
      // workdir was resolved (and memoized on the entry) by the guarded setup.
      void storage.sessions
        .setSandbox({ id: session.id, sandboxId: target.id, sandboxWorkdir: sessionEntry.workdir ?? '' })
        .catch(() => {});
      const tokenRegistration: GithubTokenRegistration = {
        inject: freshToken => {
          if (!target.setEnv) {
            throw new Error('The active sandbox provider does not support runtime GitHub token refresh.');
          }
          target.setEnv(env => ({ ...env, GH_TOKEN: freshToken }));
          tokenRegistration.ghToken = freshToken;
        },
        patKind,
        ghToken: ghCliToken,
        generation: 0,
        tokenReplacementPending: false,
      };
      githubTokenInjectors.set(workspaceId, tokenRegistration);
      registerGithubTokenContext(tokenRegistration);
      // Project skill roots were reported empty by the unmaterialized-source
      // guard before the checkout existed; rescan now. Fire-and-forget.
      void constructedWorkspaces
        .get(workspaceId)
        ?.skills?.refresh()
        .catch(() => {});
    };

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a sandbox provider whose instances implement setEnv (support runtime env mutation)
2. Update your custom sandbox adapter to implement setEnv(fn) that applies env updates to the running sandbox
3. If runtime refresh isn't needed, provide a long-lived token (PAT) so inject() is never invoked
4. Check the provider version and upgrade to one matching the sandbox contract expected by workspace.ts

Example fix

// before
const sandbox = { start: async () => {}, exec: async () => {} }; // no setEnv
// after
const sandbox = {
  start: async () => {},
  exec: async () => {},
  setEnv(update) { this.env = update(this.env ?? {}); },
};

const instance = await resolveSandbox(config);
if (typeof instance.setEnv !== 'function') {
  throw new Error('Sandbox provider must implement setEnv for GitHub token refresh');
}

function supportsRuntimeEnv(s) {
  return typeof s === 'object' && s !== null && typeof s.setEnv === 'function';
}

try {
  await startFactorySession(sessionEntry);
} catch (e) {
  if (e.message.includes('runtime GitHub token refresh')) {
    // swap to a setEnv-capable provider or use a long-lived PAT
  } else throw e;
}

When it happens

Trigger: Starting a Factory session whose materialization pipeline calls inject() (token refresh) while the configured sandbox provider returns an instance lacking setEnv — i.e. a provider that only supports static env configuration.

Common situations: Switching to a minimal/custom sandbox provider that doesn't implement the full sandbox contract, running with a local or alternative provider in dev, or a version change where setEnv was added to the provider interface but the provider wasn't updated.

Related errors

• Repository access did not include a bearer token for the Fac
• GitHub token refresh requires an active Factory sandbox work
• execa is not available in Cloudflare Workers
• Sandbox provider "${sandbox.provider}" does not support netw
• Sandbox provider "${sandbox.provider}" did not expose a publ

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/97f0cb74c12eb1da. Report an issue: GitHub.