What causes "SDK target runtime is empty" in dagger/dagger?

Fix the SDK's TargetRuntime implementation to return a valid runtime image reference.

SDK target runtime is empty

Error message

SDK target runtime is empty

What it means

After resolving the SDK's target runtime reference, initModule verifies it is non-empty. If AsRuntimeTarget succeeded but TargetRuntime returned an empty string, the SDK declares itself a runtime target without providing a usable runtime reference — treated as a misconfigured SDK and rejected with this error.

Source

Thrown at core/schema/workspace_module_init.go:151

	loadedSDK, err := s.loadWorkspaceSDK(ctx, ws, staged.ConfigDir, sdkRef)
	if err != nil {
		return res, scope, err
	}

	// By default the SDK module is also the runtime. SDKs that split authoring
	// from execution advertise RuntimeTarget and provide the runtime ref.
	defaultRuntimeRef, err := moduleEntrySourceWithPinRelativeTo(staged.ConfigDir, relPath, sdkEntry)
	if err != nil {
		return res, scope, err
	}
	runtimeRef := defaultRuntimeRef
	if target, ok := loadedSDK.AsRuntimeTarget(); ok {
		runtimeRef, err = target.TargetRuntime(ctx)
		if err != nil {
			return res, scope, fmt.Errorf("resolve SDK target runtime: %w", err)
		}
		if runtimeRef == "" {
			return res, scope, fmt.Errorf("SDK target runtime is empty")
		}
	}

	if usingDefaultPath {
		cfg.Modules[args.Name] = workspace.ModuleEntry{Source: configPath}
	}

	// Render new dagger.toml bytes through the format-preserving editor.
	newConfigBytes, err := workspace.UpdateConfigBytes(staged.Data, cfg)
	if err != nil {
		return res, scope, fmt.Errorf("update workspace config: %w", err)
	}

	// Generate the new module's config file (dagger-module.toml) ONLY. The
	// engine owns the module config; the SDK's initModule (merged in below)
	// owns every other file in the module directory — starter source, the
	// generated client, language scaffolding, etc. Emitting just the config
	// here keeps the engine and SDK changesets disjoint by construction, so

View on GitHub (pinned to 82ba2681db)

Solutions

Fix the SDK's TargetRuntime implementation to return a valid runtime image reference.
Set whatever SDK config supplies the runtime ref (it is currently empty/blank).
Pin/upgrade to an SDK version with a working runtime declaration, or use a built-in SDK instead.

Example fix

// before (custom SDK)
// func (s *SDK) TargetRuntime(ctx) (string, error) { return s.cfg.Runtime, nil } // cfg.Runtime == ""
// after
// if s.cfg.Runtime == "" { return "", fmt.Errorf("runtime ref not configured") }
// return s.cfg.Runtime, nil

Defensive patterns

Strategy: validation

Validate before calling

ref, err := sdk.TargetRuntime(ctx)
if err != nil { return err }
if ref == "" { return fmt.Errorf("SDK %q has no runtime ref configured", sdkName) }

Try / catch

res, err := ws.InitModule(ctx, args)
if err != nil && strings.Contains(err.Error(), "SDK target runtime is empty") {
	// report that the SDK's runtime configuration is blank; fix the SDK config
}

Prevention

Test custom SDKs' TargetRuntime returns a non-empty reference.
Fill in runtime config fields for custom SDKs before use.
Prefer built-in SDKs until a custom SDK declares a runtime.

When it happens

Trigger: Calling workspace.initModule with an SDK whose TargetRuntime(ctx) implementation returns "" without error — typically a custom SDK with a stubbed or incorrectly implemented TargetRuntime.

Common situations: Custom SDKs under development where the runtime ref is derived from a config field left blank; SDK versions where the default runtime constant was removed; environment-dependent derivation producing an empty result.

Related errors

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/d6c097528a9d7663. Report an issue: GitHub.