{"record":{"id":"6d6aa974572cc6a2","repo":"clockworklabs/SpacetimeDB","slug":"environment-name-cannot-use-an-enum-payload","errorCode":null,"errorMessage":"Environment '${name}' cannot use an enum payload","messagePattern":"Environment '(.+?)' cannot use an enum payload","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/server/environment.ts","lineNumber":68,"sourceCode":"    }\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`);\n        return variant.name;\n      });\n      if (values.length === 0 || new Set(values).size !== values.length)\n        throw new TypeError(\n          `Environment '${name}' needs a nonempty literal union`\n        );\n      ty =\n        values.length === 1\n          ? { tag: 'StringLiteral', value: values[0]! }","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/eddf9f5014579a50d4b67630e28b6e15cad9c4af/crates/bindings-typescript/src/server/environment.ts#L50-L86","documentation":"Enums used as environment variables must be 'simple': every variant must be a unit variant (a Product type with zero elements). Variants carrying payloads cannot be serialized to a flat environment string, so environmentDeclarations() rejects them.","triggerScenarios":"Declaring an env var whose enum type has a variant with associated data, e.g. enum Cfg { Plain, WithCount(u32) }, then building the module.","commonSituations":"Reusing a rich application enum (with data-carrying variants) directly as an environment type instead of defining a dedicated unit-only enum.","solutions":["Define a dedicated unit-only enum for the environment variable","Map payload variants to separate string variables (e.g. 'mode' plus 'mode_count')","Change the variant to carry no payload"],"exampleFix":"// before\nenum Cfg { Plain, WithCount(u32) }\n// after\nenum Cfg { Plain, WithCount } // plus a separate count env var","handlingStrategy":"validation","validationCode":"function isSimpleEnum(ty) {\n  return ty?.algebraicType?.tag === 'Sum' &&\n    ty.algebraicType.value.variants.every(v =>\n      v.algebraicType.tag === 'Product' && v.algebraicType.value.elements.length === 0);\n}","typeGuard":null,"tryCatchPattern":"try {\n  environmentDeclarations(schema);\n} catch (e) {\n  if (e instanceof TypeError && /cannot use an enum payload/.test(e.message)) {\n    console.error('Define a unit-only enum for this env var');\n  } else throw e;\n}","preventionTips":["Keep env enums payload-free; move data into separate variables","Never reuse rich application enums as env types","Check enum definitions when introducing new env vars"],"tags":["environment","enum","validation","typescript"],"backgroundTag":"unsupported-enum-value","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"}