clockworklabs/SpacetimeDB · error · TypeError

Too many environment declarations

Error message

Too many environment declarations

What it means

The schema declares more environment variables than the SDK allows. environmentDeclarations() converts an EnvironmentSchema into artifact metadata (no values are embedded), and it hard-caps the number of declarations at MAX_ENV_VARS to keep generated artifacts and server-side environment tables bounded. It throws a TypeError before doing any per-entry validation.

Solutions

1. Reduce the number of environment declarations in the module's EnvironmentSchema to at most MAX_ENV_VARS
2. Move non-critical settings out of the module environment into config fetched at runtime
3. Check the schema size before calling with Object.keys(schema).length and fail early with a clear message

Example fix

// before
const schema = { A: str, B: str, /* ... hundreds of keys */ };
environmentDeclarations(schema);
// after
const schema = { A: str, B: str }; // keep only <= MAX_ENV_VARS keys
if (Object.keys(schema).length > MAX_ENV_VARS) throw new Error('trim env block');
environmentDeclarations(schema);

function assertEnvSchemaSize(schema) {
  if (Object.keys(schema).length > MAX_ENV_VARS) {
    throw new RangeError(`Env schema has ${Object.keys(schema).length} entries; max is ${MAX_ENV_VARS}`);
  }
}
assertEnvSchemaSize(schema); // run before environmentDeclarations(schema)

const isEnvSchemaWithinLimit = (s: object): s is EnvironmentSchema => Object.keys(s).length <= MAX_ENV_VARS;

When it happens

Trigger: Calling environmentDeclarations() (directly or via ctx/invalid codegen paths) with an EnvironmentSchema whose Object.entries length exceeds MAX_ENV_VARS, e.g. a module exporting a very large env block.

Common situations: Codebases that accumulate dozens of env-driven feature flags or model endpoints in a SpacetimeDB module; porting a dot-env style config wholesale into the module environment instead of trimming it.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Environment ' ' cannot use an enum payload
• Environment ' ' literal is too long
• Environment ' ' must be a string or simple enum
• Environment ' ' needs a nonempty literal union
• Invalid environment declaration name

AI-assisted analysis of clockworklabs/SpacetimeDB@eddf9f5014 (2026-09-20). Data as JSON: /api/errors/73567ece11ccc1cf. Report an issue: GitHub.

Appendix: source

Thrown at crates/bindings-typescript/src/server/environment.ts:42

      // The host rejects undeclared keys and missing required values. Optional
      // named access uses undefined; the generic ABI accessor retains null.
      return env_get(key) ?? undefined;
    },
  }
);
export type {
  Environment,
  EnvironmentFor,
  EnvironmentSchema,
} from '../lib/environment';

/** Produce metadata only. No environment value is embedded in the artifact. */
export function environmentDeclarations(
  schema: EnvironmentSchema
): EnvironmentDeclaration[] {
  const entries = Object.entries(schema);
  if (entries.length > MAX_ENV_VARS)
    throw new TypeError('Too many environment declarations');
  const bytes = new TextEncoder();
  return entries.map(([name, definition]) => {
    if (
      !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ||
      bytes.encode(name).length > MAX_ENV_KEY_BYTES
    ) {
      throw new TypeError('Invalid environment declaration name');
    }
    const optional = definition instanceof OptionBuilder;
    const inner = optional ? definition.value : definition;
    let ty: EnvVarType;
    if (inner instanceof StringBuilder) {
      ty = { tag: 'String' };
    } else {
      const type: AlgebraicType = inner?.algebraicType;
      if (type?.tag !== 'Sum' || !('variants' in inner)) {
        throw new TypeError(
          `Environment '${name}' must be a string or simple enum`

View on GitHub (pinned to eddf9f5014)