dagger/dagger · error

remote workspace %q: %w

Error message

remote workspace %q: %w

What it means

loadWorkspaceFromRemote wraps any failure from srv.cloneGitTree while cloning the git tree for a remote workspace reference. The outer message names the workspace ref that failed; the inner error carries the actual cause (clone failure, bad version, network, auth). Dagger throws it whenever a remote workspace ref (e.g. passed to WithWorkspace or workspace loading) cannot be materialized from git.

Source

Thrown at engine/server/session_workspaces.go:368

	if subdir == "" || subdir == "." {
		return ".", nil
	}
	if !filepath.IsLocal(subdir) {
		return "", fmt.Errorf("path points outside repository: %q", subdir)
	}
	return subdir, nil
}

// loadWorkspaceFromRemote clones a git repo and detects/loads the workspace from it.
func (srv *Server) loadWorkspaceFromRemote(ctx context.Context, client *daggerClient, remoteRef string) error {
	parsedRef, err := parseWorkspaceRemoteRef(ctx, remoteRef)
	if err != nil {
		return fmt.Errorf("remote workspace %q: parsing git ref: %w", remoteRef, err)
	}

	tree, gitRef, err := srv.cloneGitTree(ctx, client.dag, parsedRef.cloneRef, parsedRef.version)
	if err != nil {
		return fmt.Errorf("remote workspace %q: %w", remoteRef, err)
	}

	resolveLocalRef := func(ws *workspace.Workspace, relPath string) string {
		subPath := filepath.Join(ws.Root, relPath)
		return core.GitRefString(parsedRef.cloneRef, subPath, parsedRef.version)
	}

	return srv.detectAndLoadWorkspaceWithRootfs(ctx, client,
		&core.DirectoryStatFS{Dir: tree},
		func(ctx context.Context, path string) ([]byte, error) {
			return core.DirectoryReadFile(ctx, tree, path)
		},
		parsedRef.workspaceSubdir,
		resolveLocalRef,
		func(ws *workspace.Workspace) string {
			return remoteWorkspaceAddress(parsedRef.cloneRef, ws.Cwd, parsedRef.version)
		},
		false, // isLocal

View on GitHub (pinned to 82ba2681db)

Solutions

1. Read the wrapped inner error to see whether it is auth, DNS, or a missing ref, and fix that specific cause.
2. Verify the ref with `git ls-remote <repo> <version>` from the same machine/container.
3. For private repos, ensure credentials (token, SSH key, or git credential helper) are available to the engine.
4. Pin to a commit SHA or an existing tag instead of a moving/renamed ref.

Example fix

// before: pinned ref deleted upstream
WithWorkspace("github.com/acme/widgets@v9.9.9")
// after: pin to an existing tag/SHA
WithWorkspace("github.com/acme/widgets@v1.4.2")

git ls-remote https://github.com/acme/widgets.git v1.4.2 || echo 'ref not reachable before calling the API'

try {
  await loadRemoteWorkspace(ref)
} catch (e) {
  if (/remote workspace .*:/.test(String(e))) {
    // inspect wrapped cause; retry transient network errors with backoff,
    // fail fast on auth or unknown-ref errors
  }
}

When it happens

Trigger: Calling loadWorkspaceFromRemote (via loadWorkspaceFromDeclaredRef) with a remote ref whose repo cannot be cloned: unknown or unreachable repo, non-existent branch/tag/version, network outage, or private repo without credentials.

Common situations: Typo in the git URL or ref, pinning a version that was force-deleted, CI runner without SSH keys/tokens for a private repo, offline environments, or a repo moved to a new host.

Related errors

• load contextual git repository: %w
• cloning repo: %w
• failed to generate patch: %w
• remove temporary octopus merge git repository: %w
• git %v: %w: %s

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