# Atlas TUI error: Creating workspace failed > Read the message in the toast body of Creating workspace failed. It carries the real cause: a worktree, git, or copy failure. Atlas shows a toast titled "Creating workspace failed" when the control-plane workspace call throws, and the toast body carries the real cause, so read the message in the toast body first: it names the underlying worktree, git, or copy failure. Confirm the project is a git repository if the workspace adapter is worktree-based, because that adapter requires an instance context, then check free disk space and directory permissions at the copy destination. A related failure, No project copy directory returned, throws its own error before the toast when a copy completes without returning a directory. ## Symptom A toast titled "Creating workspace failed" appears in the Atlas TUI with the underlying error message in its body. A related failure reads: No project copy directory returned. ## Cause The Atlas workspace and move prompts catch failures from the control-plane workspace call and surface them as an error toast with errorMessage(err). The underlying failure is a worktree, git, or copy problem. A copy that returns no directory throws its own error, No project copy directory returned, before the toast is shown. ## Fix 1. Read the message in the toast body of Creating workspace failed. It carries the real cause: a worktree, git, or copy failure, not a generic Atlas error. 2. Confirm the project is a git repository if the workspace adapter is worktree-based. That adapter requires an instance context and cannot operate on a plain directory. 3. Check free disk space and directory permissions at the copy destination, since a copy that cannot write produces the failure. 4. If you see No project copy directory returned, treat it as a copy that completed without producing a directory, and fix the destination before retrying. 5. Retry from the project list once the underlying git or filesystem problem is fixed, and confirm no Creating workspace failed toast appears. ## Why does Atlas show Creating workspace failed Atlas shows Creating workspace failed because the workspace and move prompts catch failures from the control-plane workspace call and surface them as an error toast with errorMessage(err). The title is generic on purpose, and the real cause sits in the toast body, where it names 1 of 3 failures: worktree, git, or copy. Creating a workspace in Atlas means asking the control plane to produce an isolated place for a session to work, either by creating a git worktree or by copying the project. Both paths can fail for ordinary reasons: the project is not a git repository, git refuses the worktree, the destination is not writable, or the disk is full. Atlas does not translate those failures into its own vocabulary. It passes the underlying message straight through with errorMessage(err), so the body of the toast is the diagnostic, not the title. ## How to read the error inside the Creating workspace failed toast Read the message in the toast body of Atlas's Creating workspace failed. Because the workspace prompt surfaces errors with errorMessage(err), the body carries the underlying error text rather than an Atlas paraphrase, and it will match 1 of 3 families of cause: a worktree failure, a git failure, or a copy failure. Match the body text to the cause. A git message points at the repository itself: a detached state, a branch already checked out in another worktree, or a repository that git will not accept. A filesystem message points at the copy destination: permission denied, no space left, or a path that does not exist. Fixing the problem the body names and retrying is far faster than guessing from the title, which is the same for every cause. ## Why the worktree-based Atlas workspace adapter needs a git repository As of 2026, the worktree-based Atlas workspace adapter requires the project to be a git repository, and it requires an instance context. Pointing Atlas at a plain directory that has never been initialized with git leaves the adapter with nothing to create a worktree from, and the Creating workspace failed toast is the result. Confirm the project is a git repository if the workspace adapter is worktree-based. Git is central to how Atlas works generally: Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf, and Atlas snapshots file changes as git patches so edits can be diffed and rolled back. A workspace built on worktrees is the same bet. If the project genuinely is not under git and you cannot make it so, the worktree adapter is not the right adapter for that project. ## How to fix No project copy directory returned in Atlas No project copy directory returned is an Atlas error thrown by the copy path itself, before the Creating workspace failed toast appears. The copy finished but handed back 0 directories, so the workspace has nothing to point at. Check free disk space and directory permissions at the copy destination. Treat No project copy directory returned as a destination problem. Check free disk space and directory permissions at the copy destination, because a copy that cannot write, or that writes nowhere, cannot hand back a directory. Confirm the destination path exists and that the account running Atlas can create directories under it. Once the destination is writable and has room, retry from the project list. The caveat is honest: Atlas reports that no directory came back, not why the copy produced none, so the filesystem check is on you. ## How to verify the workspace was created Verify an Atlas workspace by retrying from the project list once the underlying git or filesystem problem is fixed. A successful creation produces 0 toasts, because the workspace and move prompts raise an error toast only when the control-plane workspace call throws, so silence is the success signal. After a successful creation, the workspace exists and the session can work inside it in isolation from your main checkout. If the toast reappears, read its body again: fixing a git problem can reveal a filesystem problem behind it, and the body will have changed even though the title has not. Retry from the project list rather than from a stale view so the prompt acts on the current project state. ## FAQ ### Why does Atlas say Creating workspace failed? The control-plane workspace call threw, and the Atlas workspace and move prompts surfaced it as an error toast with errorMessage(err). The real cause, a worktree, git, or copy failure, is in the toast body. ### What does No project copy directory returned mean in Atlas? A project copy completed without returning a directory, so Atlas throws its own error before the toast. Check free disk space and directory permissions at the copy destination, then retry. ### Does the Atlas workspace need a git repository? If the workspace adapter is worktree-based, yes. Confirm the project is a git repository, because the worktree adapter requires an instance context and cannot build a worktree from a plain directory. ### Where is the real error for a failed Atlas workspace? In the toast body. Atlas surfaces the underlying failure with errorMessage(err), so the body carries the worktree, git, or copy error text while the title stays the same for every cause. ### How do I fix an Atlas workspace copy that fails on permissions? Check free disk space and directory permissions at the copy destination. The copy must be able to create a directory there, and a destination the Atlas process cannot write to produces the Creating workspace failed toast. ### Should I retry Atlas workspace creation immediately? Retry from the project list only once the underlying git or filesystem problem named in the toast body is fixed. Retrying without a change reproduces the same Creating workspace failed toast. ### Does a failed Atlas workspace creation break my project? No. The workspace and move prompts catch the failure and show an error toast rather than crashing the Atlas TUI, and your project checkout is left as it was. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/tui-workspace-creation-failed Source of truth: aeo_pages row `/resources/troubleshooting/tui-workspace-creation-failed` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.