clockworklabs/SpacetimeDB · error · TypeError

Environment ' ' literal is too long

Error message

Environment '${name}' literal is too long

What it means

An enum variant's name is the literal string that will appear in the environment, so its UTF-8 encoding must fit within MAX_ENV_VALUE_BYTES. Longer names would be truncated or rejected downstream, so environmentDeclarations() fails early.

Solutions

1. Shorten the variant name below MAX_ENV_VALUE_BYTES
2. Rename the case to a concise token and document it
3. Split semantics into multiple shorter variables

Example fix

// before
enum Mode { VeryLongDeploymentModeNameThatExceedsTheByteLimit }
// after
enum Mode { Prod }

function assertShortVariantNames(ty) {
  const enc = new TextEncoder();
  for (const v of ty.algebraicType.value.variants) {
    if (enc.encode(v.name).length > MAX_ENV_VALUE_BYTES) throw new RangeError(`Variant name too long: ${v.name}`);
  }
}

const fitsValueLimit = (name: string): boolean => new TextEncoder().encode(name).length <= MAX_ENV_VALUE_BYTES;

When it happens

Trigger: Defining an enum variant with an extremely long name (UTF-8 bytes over MAX_ENV_VALUE_BYTES) and using it as an environment variable type.

Common situations: Very verbose variant names like 'DeploymentModeProductionCanaryStagingOverride'; generated enums with long descriptive case names.

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 ' ' enum cases must have names
• Environment ' ' needs a nonempty literal union
• Too many environment declarations
• Environment key count exceeds limit

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

Appendix: source

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

        throw new TypeError(
          `Environment '${name}' must be a string or simple enum`
        );
      }
      const values = type.value.variants.map(variant => {
        if (
          variant.algebraicType.tag !== 'Product' ||
          variant.algebraicType.value.elements.length !== 0
        ) {
          throw new TypeError(
            `Environment '${name}' cannot use an enum payload`
          );
        }
        if (typeof variant.name !== 'string')
          throw new TypeError(
            `Environment '${name}' enum cases must have names`
          );
        if (bytes.encode(variant.name).length > MAX_ENV_VALUE_BYTES)
          throw new TypeError(`Environment '${name}' literal is too long`);
        return variant.name;
      });
      if (values.length === 0 || new Set(values).size !== values.length)
        throw new TypeError(
          `Environment '${name}' needs a nonempty literal union`
        );
      ty =
        values.length === 1
          ? { tag: 'StringLiteral', value: values[0]! }
          : { tag: 'Union', value: values };
    }
    return { name, ty, optional };
  });
}

View on GitHub (pinned to eddf9f5014)