Fix Codex SUN_LEN Socket Path Errors on macOS

Why SUN_LEN appears in Codex on macOS

A Codex session can fail before it reaches your code. The terminal may report that an app server did not become ready, followed by an error saying a path must be shorter than SUN_LEN. This is not a repository problem and it is not evidence that the current project is corrupt. It is a Unix-domain socket pathname problem.

The failure becomes especially likely when another tool manages Codex under a deeply nested home directory. A launcher can add its own runtime folder, account folder, package folder, and control directory before Codex appends a socket filename. Each component looks harmless on its own. The combined pathname can cross the operating system limit before the daemon binds its socket.

This distinction matters because the wrong diagnosis leads to destructive fixes. Reinstalling a repository, deleting project files, changing Git branches, or disabling unrelated automation does not shorten the control socket. The useful question is much narrower: which process constructs the socket path, what home directory does it see, and can that path be made shorter without losing the session state you actually need?

This guide focuses on that diagnostic path. It also connects to a broader RayLabs principle: when an automated tool fails at a boundary, verify the boundary itself before changing the system around it. The same approach appears in schema-first validation for automated pipelines.

What the error actually means

Unix-domain sockets let local processes communicate through a filesystem-like address. Unlike a normal file path, that address is stored in a fixed-size field in the socket address structure. A program can therefore create ordinary files under a deep directory while failing when it tries to bind a socket beneath the same directory.

That explains the confusing symptom. Codex can start, read configuration, discover packages, and then fail when its background app server creates a control socket. The visible pathname may include a managed Codex home plus something similar to app-server-control/app-server-control.sock. The failure happens at socket creation, not at repository checkout or model authentication.

OpenAI has an open Codex issue specifically describing codex app-server daemon commands failing with “path must be shorter than SUN_LEN” when CODEX_HOME is a deep path on macOS. Orca also has an open issue about keeping managed account homes within the macOS Unix socket path limit. Those reports are valuable because they move the diagnosis from speculation to a reproducible integration constraint.

Treat the exact number of usable characters as an implementation detail rather than a magic constant to hard-code into your own launcher. Encoding, terminating bytes, and platform definitions matter. The durable rule is simpler: socket control paths must stay comfortably short.

Confirm the failure before changing anything

Start with the error text. Capture the full socket pathname reported by Codex and identify the directory prefix contributed by the launcher. If the message names app-server-control.sock and explicitly says the path must be shorter than SUN_LEN, you already have a strong signal that shortening the control path is the relevant experiment.

Next, compare two launches of the same Codex installation. Run it through the managed environment that fails, then run an equivalent command from a shorter home or with the daemon bypassed if the installed Codex version explicitly offers that mode. The goal is not to adopt a workaround permanently. The goal is to isolate the daemon socket as the variable.

Do not mix this experiment with upgrades, repository changes, credential resets, and configuration rewrites. If five variables change at once, a successful retry teaches you almost nothing. A good diagnostic changes one path boundary and keeps the project, account, command, and model configuration stable.

Also record the Codex version and launcher version. Path handling can change between releases. A workaround that was necessary for one build may become unnecessary after an upstream fix, while a launcher may later shorten its managed home automatically.

Measure the effective Codex home

The path shown in the error is more useful than the path you intended to configure. Managed environments frequently rewrite home directories so that multiple accounts or agents can remain isolated. That isolation is useful, but it can create a surprisingly long effective CODEX_HOME.

Break the failing pathname into components. Separate the launcher-managed prefix, Codex runtime home, package or account segment, control directory, and socket filename. This makes the largest contributor obvious. In many cases the project directory is not part of the socket path at all, so moving the Git repository would add risk without addressing the cause.

A useful rule for orchestration tools is to keep runtime state near a short, dedicated root. Human-readable names belong in metadata and dashboards, not necessarily in every filesystem component. A directory can be named with a compact stable identifier while a separate manifest stores the descriptive account or workspace label.

Avoid symbolic-link tricks until you know how the application resolves paths. Some runtimes call realpath before binding and end up using the expanded target, which removes the apparent benefit. A genuinely short configured home is easier to reason about than a short alias pointing to a long physical path.

Prefer a short managed runtime root

If you control the launcher, the cleanest design is to shorten the managed Codex runtime root while preserving isolation. Keep project worktrees wherever they belong. Move only ephemeral or recreatable runtime state that contributes to the socket pathname.

For example, a launcher that currently nests runtime state under several descriptive application-support directories can allocate a compact per-account directory under a shorter root. The launcher should then pass that location through the supported Codex environment or invocation mechanism. It should not patch Codex binaries or rewrite internal package files.

The change needs a migration plan. Existing sessions may reference state in the old home, and blindly moving every file can preserve stale sockets or locks. Decide which data is authoritative, which data is cache, and which state Codex can regenerate. Back up important configuration before testing a migration.

For multi-agent setups, derive compact directory names from stable IDs rather than display names. This prevents a future account with a long label from reintroducing the same problem. It also makes the maximum socket length predictable before a process starts.

Use daemon bypass only as a diagnostic or documented fallback

Some Codex builds expose a way to run commands without the background app server. When the installed command itself advertises such an option, it can be a useful diagnostic: if the same operation works without the daemon, the socket control path becomes an even stronger suspect.

A daemon bypass is not automatically the best permanent configuration. Background services may provide session continuity, lower startup overhead, or features expected by the surrounding orchestrator. Disabling them can change behavior that has nothing to do with the original error.

This is why copying a command from an issue comment without checking the installed CLI is risky. Verify the help output for the exact Codex version you run. If a flag is absent, do not invent it. If it is present, document whether the launcher supports forwarding it for resume and fork operations as well as a fresh session.

The fallback should also be reversible. Once OpenAI or the orchestrator ships a path fix, you should be able to remove the bypass and return to the normal daemon architecture without reconstructing the environment.

Why moving the repository usually does not help

The visible failure often happens while working inside a project, so moving that project to a shorter folder feels intuitive. But the socket may live entirely under CODEX_HOME or another runtime directory. If the failing pathname printed by Codex does not contain the repository path, relocating the repository cannot shorten it.

This is a general debugging lesson: optimize the path that appears in the failing system call, not the path that happens to be visible in your shell prompt. The same discipline prevents wasted effort in CI, where a build error may come from a cache or temporary directory rather than the checkout itself.

Moving a repository can also create secondary problems. IDE metadata, worktrees, scripts, local environment files, and absolute references may all need adjustment. That is too much collateral change for a socket-path experiment.

Keep the repository stable while you test the runtime root. Once the daemon starts successfully with the same project and command, you have a much cleaner causal result.

Design orchestrators so the bug cannot return

An orchestrator that provisions Codex homes can prevent this class of failure before launching a process. Construct the longest expected control socket path, measure its encoded length, and reject or shorten an unsafe runtime root early. The error should name the generated path and the configuration field that controls it.

Do not wait for Codex to time out and then surface a generic “app server did not become ready” message. A preflight check can turn a confusing runtime failure into an immediate configuration error. It also avoids repeatedly spawning a daemon that cannot bind.

Keep runtime roots short by policy. Use compact stable IDs for accounts, sessions, and agents. Store verbose labels separately. Test the policy on macOS in CI or a dedicated integration test because Linux limits and behavior may differ.

If the orchestrator creates worktrees for parallel agents, keep that concern separate from Codex runtime state. Worktree paths can be descriptive because they are ordinary filesystem paths. Socket control paths need a stricter budget.

Preserve session continuity during a path migration

The most delicate part of shortening a managed home is not creating the new directory. It is deciding what should follow the user. A launcher may store authentication, session indexes, configuration, cached packages, and transient daemon state under one tree even though those categories have different lifetimes.

Inventory the old home before migration. Preserve configuration and credentials only through supported mechanisms. Treat socket files, process IDs, and lock files as transient. Copying a stale control socket into a new home cannot reconnect a dead daemon and may confuse startup logic.

For session resume, verify behavior with a disposable session first. Create a small session, stop the launcher cleanly, migrate using the proposed procedure, and confirm that the supported resume command can see the expected state. If it cannot, restore the backup and refine the migration rather than experimenting on valuable work.

This is similar to reliable publishing automation: state transitions should be explicit and recoverable. RayLabs uses the same principle when discussing concurrent Git commits in automated publishing: preserve the authoritative state, avoid forceful mutation, and retry from a known boundary.

A practical verification sequence

A reliable fix should survive more than one successful launch. First, record the original failing pathname and versions. Second, configure the shorter runtime root without moving the repository. Third, start a fresh Codex session through the same orchestrator and confirm that the daemon becomes ready.

Then test the operations that depend most heavily on session infrastructure. Resume the session, fork it if your workflow uses forks, stop and restart the orchestrator, and confirm that another account or agent still receives an isolated home. A fix that works only for a fresh command but breaks resume is incomplete.

After that, inspect for stale processes or control directories under the old root. Clean them only after you have confirmed they are no longer authoritative. Keep the backup until the new path has survived normal usage.

Finally, remove temporary diagnostic flags. The target state is a normal supported Codex invocation with a runtime root that leaves enough room for its control socket. Document the path budget in the orchestrator so a future refactor does not silently add several nested directories.

What to do while upstream fixes are still open

As of September 26, 2026, the relevant OpenAI Codex and Orca reports referenced by this article are open. That means local mitigation should be conservative and easy to remove. Prefer configuration changes at the launcher boundary over patches to Codex internals.

Track the upstream issues by symptom and version, not by assuming every daemon startup failure has the same cause. If a future error no longer mentions SUN_LEN, inspect it independently. Authentication failures, stale processes, permission problems, and incompatible versions can all prevent an app server from becoming ready for different reasons.

When an upstream release claims to fix the path problem, retest the original long-path scenario in a disposable environment. If it succeeds, simplify your local workaround. Keeping obsolete compatibility code forever creates its own maintenance burden.

The key is to make the workaround boring: one short runtime root, one documented migration, one preflight check, and a clear path back to defaults.

Conclusion

A SUN_LEN failure is a path-budget problem at a local IPC boundary. Diagnose the socket path Codex actually tries to bind, not the repository path or the directory you assume it uses. Deep launcher-managed homes can push an otherwise valid Codex installation over the macOS Unix-domain socket limit.

The safest response is targeted. Reproduce the failure, measure the effective runtime path, shorten the managed home, preserve only authoritative session state, and verify fresh, resume, and restart flows. Use daemon bypass only when the installed CLI supports it and when you understand the behavioral trade-off.

For orchestrator authors, add a preflight path-budget check and compact runtime IDs so users never reach the low-level socket error. For users, keep the workaround reversible while the upstream reports remain open.

Most importantly, do not repair unrelated systems to compensate for one boundary failure. A precise diagnosis produces a smaller fix, a safer rollback, and evidence you can reuse when the next integration layer fails.