Environment key : numeric config input must use JSON number…

Error message

Environment key {:?}: numeric config input must use JSON number syntax

What it means

During parsing, numeric tokens (including JSON5 hex/octal/big numbers) are masked with placeholder strings and restored afterwards. Inside an environment entry (`env_key` set), the token must parse as a JSON number; if it does not (e.g. JSON5-only syntax like `0xFF` used as an env value), `restore` fails naming the environment key.

Solutions

Rewrite the value using strict JSON number syntax (e.g. `31` instead of `0x1F`).
Quote the value as a string if the exact token text matters (e.g. `"0x1F"`).
Remove underscores/plus signs from numeric env values.

Example fix

// before (config env)
PORT: 0x1F90
// after (config env)
PORT: 8080

Defensive patterns

Strategy: validation

Validate before calling

fn is_json_number_literal(tok: &str) -> bool { tok.parse::<serde_json::Number>().is_ok() } // rejects 0x1F, 1_000, +5

Type guard

fn is_strict_json_number(s: &str) -> bool { s.parse::<f64>().is_ok() && !s.starts_with('+') && !s.contains('_') && !s.starts_with("0x") }

Try / catch

match result { Err(e) if e.to_string().contains("numeric config input must use JSON number syntax") => { eprintln!("Rewrite the named env key's value as a JSON number or quote it as a string"); }, Err(e) => return Err(e), Ok(v) => v }

Prevention

Use decimal JSON numbers only in env values — no hex, octal, underscores, or leading `+`.
Quote values like `"0x1F"` if the literal text matters.
Keep env keys string-or-decimal-number only.

When it happens

Trigger: An env config value written with JSON5 numeric extensions such as `0x1F`, `1_000`, or a leading `+`, which are not valid JSON number syntax and thus rejected for environment values.

Common situations: Using JavaScript-style hex or underscore-separated literals in spacetimedb config env values; values intended as strings (e.g. IDs with leading zeros) parsed as numbers.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at crates/cli/src/spacetime_config/environment.rs:130

        {
            return anyhow::anyhow!("unknown field `{field}`");
        }
        anyhow::anyhow!("Invalid configuration structure")
    })
}

fn is_space(ch: char) -> bool {
    ch.is_whitespace() || ch == '\u{feff}'
}

fn restore(value: &mut Value, prefix: &str, numbers: &[&str], env_key: Option<&str>) -> anyhow::Result<()> {
    match value {
        Value::String(s) => {
            if let Some(index) = s.strip_prefix(prefix).and_then(|s| s.parse::<usize>().ok()) {
                let token = numbers[index];
                *value = if let Some(env_key) = env_key {
                    Value::Number(token.parse().map_err(|_| {
                        anyhow::anyhow!(
                            "Environment key {:?}: numeric config input must use JSON number syntax",
                            env_key
                        )
                    })?)
                } else {
                    // Preserve existing JSON5 conveniences outside env. JSON numbers retain
                    // arbitrary precision throughout layering and config serialization.
                    token
                        .parse()
                        .map(Value::Number)
                        .or_else(|_| json5::from_str(token))
                        .map_err(|_| anyhow::anyhow!("Invalid numeric configuration input"))?
                };
            }
        }
        Value::Object(object) => {
            for (key, value) in object {
                if key == "env" && env_key.is_none() {

View on GitHub (pinned to eddf9f5014)