{"record":{"id":"73567ece11ccc1cf","repo":"clockworklabs/SpacetimeDB","slug":"too-many-environment-declarations","errorCode":null,"errorMessage":"Too many environment declarations","messagePattern":"Too many environment declarations","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/server/environment.ts","lineNumber":42,"sourceCode":"      // The host rejects undeclared keys and missing required values. Optional\n      // named access uses undefined; the generic ABI accessor retains null.\n      return env_get(key) ?? undefined;\n    },\n  }\n);\nexport type {\n  Environment,\n  EnvironmentFor,\n  EnvironmentSchema,\n} from '../lib/environment';\n\n/** Produce metadata only. No environment value is embedded in the artifact. */\nexport function environmentDeclarations(\n  schema: EnvironmentSchema\n): EnvironmentDeclaration[] {\n  const entries = Object.entries(schema);\n  if (entries.length > MAX_ENV_VARS)\n    throw new TypeError('Too many environment declarations');\n  const bytes = new TextEncoder();\n  return entries.map(([name, definition]) => {\n    if (\n      !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ||\n      bytes.encode(name).length > MAX_ENV_KEY_BYTES\n    ) {\n      throw new TypeError('Invalid environment declaration name');\n    }\n    const optional = definition instanceof OptionBuilder;\n    const inner = optional ? definition.value : definition;\n    let ty: EnvVarType;\n    if (inner instanceof StringBuilder) {\n      ty = { tag: 'String' };\n    } else {\n      const type: AlgebraicType = inner?.algebraicType;\n      if (type?.tag !== 'Sum' || !('variants' in inner)) {\n        throw new TypeError(\n          `Environment '${name}' must be a string or simple enum`","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/eddf9f5014579a50d4b67630e28b6e15cad9c4af/crates/bindings-typescript/src/server/environment.ts#L24-L60","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reduce the number of environment declarations in the module's EnvironmentSchema to at most MAX_ENV_VARS","Move non-critical settings out of the module environment into config fetched at runtime","Check the schema size before calling with Object.keys(schema).length and fail early with a clear message"],"exampleFix":"// before\nconst schema = { A: str, B: str, /* ... hundreds of keys */ };\nenvironmentDeclarations(schema);\n// after\nconst schema = { A: str, B: str }; // keep only <= MAX_ENV_VARS keys\nif (Object.keys(schema).length > MAX_ENV_VARS) throw new Error('trim env block');\nenvironmentDeclarations(schema);","handlingStrategy":"validation","validationCode":"function assertEnvSchemaSize(schema) {\n  if (Object.keys(schema).length > MAX_ENV_VARS) {\n    throw new RangeError(`Env schema has ${Object.keys(schema).length} entries; max is ${MAX_ENV_VARS}`);\n  }\n}\nassertEnvSchemaSize(schema); // run before environmentDeclarations(schema)","typeGuard":"const isEnvSchemaWithinLimit = (s: object): s is EnvironmentSchema => Object.keys(s).length <= MAX_ENV_VARS;","tryCatchPattern":null,"preventionTips":["Keep module environment blocks small; prefer runtime config for long lists","Add a unit test asserting the schema size stays under MAX_ENV_VARS","Review new env additions in code review"],"tags":["environment","validation","typescript","limits"],"backgroundTag":"value-out-of-range","analyzedSha":"eddf9f5014579a50d4b67630e28b6e15cad9c4af","analyzedAt":"2026-09-20T12:15:59.611Z","contentChangedAt":"2026-09-20T12:15:59.611Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}