{"record":{"id":"15446ff3173e4f63","repo":"clockworklabs/SpacetimeDB","slug":"environment-name-must-be-a-string-or-simple-enum","errorCode":null,"errorMessage":"Environment '${name}' must be a string or simple enum","messagePattern":"Environment '(.+?)' must be a string or simple enum","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/server/environment.ts","lineNumber":59,"sourceCode":"  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`\n        );\n      }\n      const values = type.value.variants.map(variant => {\n        if (\n          variant.algebraicType.tag !== 'Product' ||\n          variant.algebraicType.value.elements.length !== 0\n        ) {\n          throw new TypeError(\n            `Environment '${name}' cannot use an enum payload`\n          );\n        }\n        if (typeof variant.name !== 'string')\n          throw new TypeError(\n            `Environment '${name}' enum cases must have names`\n          );\n        if (bytes.encode(variant.name).length > MAX_ENV_VALUE_BYTES)\n          throw new TypeError(`Environment '${name}' literal is too long`);","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/eddf9f5014579a50d4b67630e28b6e15cad9c4af/crates/bindings-typescript/src/server/environment.ts#L41-L77","documentation":"Environment variables may only be strings or simple enums (string-literal unions). environmentDeclarations() inspects the builder's AlgebraicType and requires a Sum type with named variants; anything else (ints, options of other types, plain products, structs) is rejected because only string-like values can be mapped to process environment values.","triggerScenarios":"Passing a builder whose inner algebraicType is not a Sum (e.g. a u32 builder, a struct builder, or undefined inner) as an environment variable value in the schema.","commonSituations":"Trying to expose a numeric port or a struct-typed config object as an env var; forgetting that only strings and enum builders are supported.","solutions":["Use StringBuilder (str) for the variable","Use an enum builder whose variants are all unit (no payloads)","Remove the unsupported type from the environment schema and read it another way"],"exampleFix":"// before\nconst schema = { port: u32 };\n// after\nconst schema = { port: str }; // or an enum of allowed values","handlingStrategy":"validation","validationCode":"function assertStringOrEnumBuilder(v) {\n  if (!(v instanceof StringBuilder) && !(v instanceof OptionBuilder && v.value instanceof Object && v.value.algebraicType?.tag === 'Sum')) {\n    throw new TypeError('Env var must be a string or simple enum');\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  environmentDeclarations(schema);\n} catch (e) {\n  if (e instanceof TypeError && /must be a string or simple enum/.test(e.message)) {\n    console.error('Env var must be str or a unit-only enum:', e.message);\n  } else throw e;\n}","preventionTips":["Only use str or enum builders in environment schemas","Never expose numeric or struct types as env vars","Document supported env types for module authors"],"tags":["environment","types","validation","typescript"],"backgroundTag":"type-mismatch","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"}