dagger/dagger · error

resolving blueprint module: %w

Error message

resolving blueprint module: %w

What it means

When the module source declares a blueprint (src.Self().Blueprint), the blueprint module is resolved with resolveModuleSourceAsModule and its failure is wrapped as 'resolving blueprint module'. The blueprint is loaded as a related entrypoint module, so a broken blueprint blocks the whole module load.

Source

Thrown at engine/server/session_workspaces.go:1767

		if i < len(src.Self().ConfigToolchains) {
			cfg = src.Self().ConfigToolchains[i]
		}
		pending := pendingRelatedModule(defaultPathContextSrc, toolchainSrc.Self(), cfg, false)
		toolchainMod, err := srv.resolveModuleSourceAsModule(ctx, dag, toolchainSrc, pending)
		if err != nil {
			return resolvedModuleLoad{}, fmt.Errorf("resolving toolchain module: %w", err)
		}
		resolved.related = append(resolved.related, resolvedServedModule{
			mod:        toolchainMod,
			entrypoint: false,
		})
	}

	if src.Self().Blueprint.Self() != nil {
		pending := pendingRelatedModule(defaultPathContextSrc, src.Self().Blueprint.Self(), src.Self().ConfigBlueprint, true)
		blueprintMod, err := srv.resolveModuleSourceAsModule(ctx, dag, src.Self().Blueprint, pending)
		if err != nil {
			return resolvedModuleLoad{}, fmt.Errorf("resolving blueprint module: %w", err)
		}
		resolved.related = append(resolved.related, resolvedServedModule{
			mod:        blueprintMod,
			entrypoint: true,
		})
		resolved.primaryEntrypoint = false
	}

	return resolved, nil
}

// serveResolvedModuleLoadsLocked serves resolved primary modules and their
// related modules (blueprints, toolchains-of-toolchains), skipping any whose
// identity an earlier batch already served. client.stateMu and client.modulesMu
// must be held.
//
// Transitive dependencies are only served for the entrypoint module — the one
// the user is interacting with via `dagger call` or `dagger shell`. This is

View on GitHub (pinned to 82ba2681db)

Solutions

1. Check the inner error to identify the failing blueprint source and cause.
2. Fix the blueprint path in the module config to point at a valid module directory.
3. Build/test the blueprint module standalone (cd blueprint && dagger develop) to surface its own errors.
4. Ensure the blueprint's dependencies and SDK resolve in the engine.

Example fix

// before
blueprint = "./blueprints/deprecated-bp" // removed
// after
blueprint = "./blueprints/main-bp" // valid module with dagger.json

// preflight: blueprint path in config resolves to a valid module
if bp := cfg.Blueprint; bp != "" { if _, err := os.Stat(filepath.Join(root, bp, "dagger.json")); err != nil { return fmt.Errorf("blueprint %q invalid", bp) } }

if err != nil && strings.Contains(err.Error(), "resolving blueprint module") { /* surface blueprint-specific guidance to user */ }

When it happens

Trigger: Loading a module whose source has a non-nil Blueprint (with ConfigBlueprint settings) where the blueprint module itself fails resolveModuleSourceAsModule: invalid blueprint path in config, blueprint source errors, or SDK/compile failures inside the blueprint module.

Common situations: Blueprint directory renamed/deleted while config still references it; blueprint module has its own broken dependencies; SDK version mismatch in the blueprint; typo'd blueprint path.

Related errors

• module name must be set
• failed to get source directory: %w
• failed to load updated blueprint: %w
• failed to get updated blueprint ID: %w
• load workspace modules and skip workspace modules are mutual

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