clockworklabs/SpacetimeDB · error · anyhow::Error

Unsupported .NET SDK version

Error message

Unsupported .NET SDK version: {}. SpacetimeDB requires .NET SDK 8.0 or 10.0.
If you have multiple versions installed, configure your project using https://learn.microsoft.com/en-us/dotnet/core/tools/global-json, or use --dotnet-version to specify the target version explicitly.

What it means

After resolving the effective .NET major (resolution order: --dotnet-version CLI flag, then global.json-selected SDK, then a single <TargetFramework> in the csproj, then the .NET 10 default), the CLI maps (major, native_aot) to a build path: 10 -> NativeAOT-LLVM, 8+AOT, 8+JIT. Any other major (6, 7, 9, unresolvable) lands here; the message includes the selected version string (or <unknown>) plus remediation hints.

Solutions

Pin a supported SDK with a global.json next to the project (the sibling error prints the exact 8.0.100/10.0.100 templates; MS docs link is in the message).
Pass `--dotnet-version 8` or `--dotnet-version 10` explicitly on the build/publish command.
Update the csproj <TargetFramework> to net8.0 or net10.0.
Migrate old .NET 7 template projects (see the companion 'deprecated .NET 7.0 WebAssembly bindings' error).

Example fix

# before
spacetime build
# after
spacetime build --dotnet-version 8

Defensive patterns

Strategy: validation

Validate before calling

# Fail fast before building if the resolved major is unsupported
MAJOR=$(dotnet --version 2>/dev/null | cut -d. -f1)
case "$MAJOR" in 8|10|"") ;; *) echo "unsupported .NET SDK $MAJOR (need 8 or 10)" >&2; exit 1 ;; esac
spacetime build

Prevention

Commit a project-level global.json pinning SDK 8 or 10 so machine defaults cannot leak in.
Set csproj TargetFramework to net8.0/net10.0 only.
Pass --dotnet-version explicitly in CI for deterministic toolchain selection.

When it happens

Trigger: `spacetime build` on a C# project whose resolved SDK major is not 8 or 10: a global.json in the project or cwd pinning 6/7/9, a csproj targeting net7.0 as the single TFM, or dotnet --version resolving to an unsupported release.

Common situations: Legacy .NET 7-era SpacetimeDB projects; machine-default SDK being a preview release picked up through a stray global.json; multi-target csprojs where no single major could be inferred and the fallback chain ended on an unsupported value.

Related errors

AI-assisted analysis of clockworklabs/SpacetimeDB@9e0d92412f (2026-08-20). Data as JSON: /api/errors/a070ee8b4ee2924e. Report an issue: GitHub.

Appendix: source

Thrown at crates/cli/src/tasks/csharp.rs:246

    let build_path = match (dotnet_major, native_aot_flag) {
        // .NET 10: always use NativeAOT-LLVM, no flag needed.
        (Some(10), _) => {
            if native_aot_flag {
                println!("Note: --native-aot is not needed with .NET 10 (NativeAOT-LLVM is used automatically).");
            }
            CsharpBuildPath::Net10Aot
        }
        // .NET 8 with --native-aot: use NativeAOT-LLVM with .NET 8 ILCompiler packages.
        (Some(8), true) => CsharpBuildPath::Net8Aot,
        // .NET 8 without flag: use the existing wasi-experimental JIT path.
        (Some(8), false) => CsharpBuildPath::Net8Jit,
        // Unsupported version.
        _ => {
            let selected_version = dotnet_major
                .map(|v| v.to_string())
                .or_else(|| dotnet_version_str.clone())
                .unwrap_or_else(|| "<unknown>".to_string());
            anyhow::bail!(
                "Unsupported .NET SDK version: {}. SpacetimeDB requires .NET SDK 8.0 or 10.0.\n\
                 If you have multiple versions installed, configure your project using \
                 https://learn.microsoft.com/en-us/dotnet/core/tools/global-json, \
                 or use --dotnet-version to specify the target version explicitly.",
                selected_version
            );
        }
    };

    let desired_sdk_major = match build_path {
        CsharpBuildPath::Net8Jit | CsharpBuildPath::Net8Aot => 8,
        CsharpBuildPath::Net10Aot => 10,
    };
    if matches!(build_path, CsharpBuildPath::Net8Aot | CsharpBuildPath::Net10Aot)
        && nativeaot_unsupported_on_host(std::env::consts::OS, Some(desired_sdk_major))
    {
        anyhow::bail!(NATIVEAOT_UNSUPPORTED_MESSAGE);
    }

View on GitHub (pinned to 9e0d92412f)