clockworklabs/SpacetimeDB · error · anyhow::Error

--unreal-module-name is required for --lang unrealcpp

Error message

--unreal-module-name is required for --lang unrealcpp

What it means

Unreal C++ codegen writes the generated plugin into a named UE C++ module, so generate requires `--unreal-module-name` (or the `unreal-module-name` config field) whenever `--lang unrealcpp` is used. It is validated immediately after `--uproject-dir`, before any build or generation runs. The name must match a module in your Unreal project's Source layout, not the SpacetimeDB module name.

Source

Thrown at crates/cli/src/subcommands/generate.rs:348

        let module_name = command_config.get_one::<String>("unreal_module_name")?;
        let module_prefix = command_config.get_one::<String>("module_prefix")?;
        let build_options = command_config
            .get_one::<String>("build_options")?
            .unwrap_or_else(String::new);
        let dotnet_version = if command_config.is_from_cli("dotnet_version") {
            command_config.get_one::<u8>("dotnet_version")?
        } else {
            let dotnet_version = command_config.get_one::<String>("dotnet_version")?;
            parse_optional_dotnet_version(dotnet_version.as_deref())?
        };

        // Validate Unreal-specific args first to preserve focused errors for this mode.
        if requested_lang == Some(Language::UnrealCpp) {
            if command_config.get_one::<PathBuf>("uproject_dir")?.is_none() {
                return Err(anyhow::anyhow!("--uproject-dir is required for --lang unrealcpp"));
            }
            if module_name.is_none() {
                return Err(anyhow::anyhow!("--unreal-module-name is required for --lang unrealcpp"));
            }
        }

        // Validate module source path for source-based generation.
        if wasm_file.is_none() && js_file.is_none() && !project_path.is_dir() {
            anyhow::bail!(
                "Could not find module source at '{}'. \
                 If this is not correct, pass --module-path or add module-path in spacetime.json. \
                 You can also pass --bin-path/--js-path to generate without building from source.",
                project_path.display()
            );
        }

        let lang = match requested_lang {
            Some(lang) => lang,
            None => {
                let client_project_dir = config_dir.unwrap_or_else(|| Path::new("."));
                let detected = detect_default_language(client_project_dir)?;

View on GitHub (pinned to 524b4487d9)

Solutions

1. Pass `--unreal-module-name <YourUEModule>` using the game/module name from your project's Source directory
2. Add `"unreal-module-name": "..."` to the unrealcpp target in spacetime.json
3. Check your .uproject's Modules list for the exact module name spelling

Example fix

# before
spacetime generate --lang unrealcpp --uproject-dir ~/Projects/MyGame

# after
spacetime generate --lang unrealcpp --uproject-dir ~/Projects/MyGame --unreal-module-name MyGame

# Guard an unrealcpp generate invocation (module name):
if [[ "$LANG_ARG" == "unrealcpp" ]]; then
  [[ -n "$UE_MODULE" ]] || { echo "unrealcpp requires --unreal-module-name" >&2; exit 2; }
  [[ -d "$UPROJECT_DIR/Source/$UE_MODULE" ]] \
    || echo "WARN: $UPROJECT_DIR/Source/$UE_MODULE does not exist yet" >&2
fi
spacetime generate --lang unrealcpp --uproject-dir "$UPROJECT_DIR" --unreal-module-name "$UE_MODULE"

When it happens

Trigger: `spacetime generate --lang unrealcpp --uproject-dir .` without `--unreal-module-name`; an unrealcpp target in spacetime.json lacking the `unreal-module-name` field.

Common situations: Following docs that only mention --uproject-dir; assuming the module name defaults to the .uproject name; copy-pasting a rust generate invocation and only changing --lang.

Related errors

• --uproject-dir is required for --lang unrealcpp
• Either --out-dir or --uproject-dir is required
• No database target matches '{}'. Available databases: {}
• Could not find module source at '{}'. If this is not correct
• Could not auto-detect client language from '{}'. If this is

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/ab97026fa7544044. Report an issue: GitHub.