Skip to main content
Join the waitlist

Troubleshooting

Use the message in the app to choose the next step. Review the result before trying another change.

These steps describe the Mac desktop app, which is preparing for private beta. Join the waitlist for access. Installing the component package does not install the desktop app.

Open or create a project

No app to start here means the folder scan found no app with a dev script. Choose Open another folder and select the app’s folder. If Fragments finds several apps, use Choose an app to select the intended one and check its displayed path and command before starting it.

If creating a project stops during installation, checking or building, open Details to read the failure. The folder made so far is kept. Resolve the reported cause, then use Retry; after stopping setup yourself, use Resume setup in the current app session. These actions do not promise to fix a network or package error by themselves.

If the destination already exists or the name is refused, edit the form to use an unused name. After a failed setup, Change the name returns to that form. Keep any existing work; an existing project can be opened instead of creating another project over it.

Start the local server

Read the reason on the start card and expand Show what it printed for the server output. The offered action depends on that failure.

Packages are missing. Use Install packages and start. Review the package-manager command and folder in the confirmation before choosing Install and start. Installation runs the project’s package scripts.

The package lockfile needs updating. A frozen install could not use the current lockfile. Install anyway allows installation to update it; review the resulting lockfile change. Choose Cancel if you need to resolve the mismatch first. Do not delete a lockfile just to hide the failure.

The port is already in use. Choose the offered Start on alternative port, or stop the other server if it is yours and you no longer need it. If the server already running is the app you want, use the offered attachment action; its source editing is read-only.

The app needs a different Node.js version. Use the version required by the project, then choose Start again. Check its version file or setup instructions. If it starts in Terminal but still cannot start from Fragments, you can attach that local server for read-only viewing.

A required app setting is missing. Set the environment variable named in the failure using the project’s setup instructions, then start again. Keep secret values out of screenshots and shared logs. For a compile error, review the named file and line; Ask your connected agent to fix it when that action is offered. Review the change before restarting.

The server stopped or did not answer in time. Read its output before using Start again. If it is still running and has a working local URL, use an existing server instead. A timeout does not establish that the app is healthy.

Use an existing server

Choose Use a server that is already running, enter its local HTTP or HTTPS address, and choose Connect. Only loopback addresses such as localhost, 127.0.0.1 and [::1] are accepted. If nothing answers, check that the server is running and that the port matches the URL it printed.

An attached server is read-only. Start the app from Fragments when you need to edit its source through the desktop workflow. Attaching a URL does not repair the project’s start command or install missing dependencies.

Connect your coding agent

Not installed and Not signed in describe your coding agent on this Mac. Choose Install or Sign in when offered. Fragments copies the appropriate command and opens Terminal; paste it there and complete the agent’s own setup. Fragments checks again when you return.

For Update needed or Off, open the offered Settings and review the agent’s configuration. In the Agents settings, use Check for updates under CLI updates when available. A failed agent turn can also offer Sign in, Update or CLI settings; follow the displayed reason. The agent’s login is separate from signing in to the app you are building.

Find an element’s source

Finding its line… means the source lookup is still running. If it ends with Line unknown or Not linked to source., read the reason and use Retry when offered, or select the live element again. A known file without a verified line is not an exact edit target.

Source linking uses supported React development information and, where needed, source maps. An unsupported or stale selection cannot be made reliable by guessing a line number. You can describe the intended element to your agent, but review the files it changes. If you attached the server, start it from Fragments to enable source editing.

Picture a page

Page pictures require macOS 15.4 or later, even though the app can run on macOS 14. For Needs signing in, use Sign in on the page and complete the app’s own login. For Needs an example, provide a real route parameter value, then choose Picture it.

For Could not be pictured or No page here, read the reason and use Open the page to inspect the route. After resolving the problem, choose Try again. If This page showed nothing, check whether it needs sign-in or more time to load; use the offered sign-in or retry action. If pictures could not start at all, use the displayed Retry.

Captured the first portion of a page means the picture is partial; read the reason on the capture receipt. A missing or incomplete picture cannot prove that a page stayed unchanged. Review the live page and the capture coverage before relying on a before-and-after comparison.

Resolve an Undo conflict

Undo checks whether the affected files still match what the change left behind. If another edit changed a file, or a deleted file was recreated, it keeps the newer work and reports the conflict. Read the named file in the change receipt and use Show when offered to reveal it in Finder.

Review and preserve the newer work before resolving the conflict. If the receipt says the change was made on another branch, return to that branch only after protecting your current work. Retry Undo checks again; it does not force an overwrite. An offered Undo action for other files can undo those files while leaving the conflicting ones in place.

Undo restores recorded project files, not the entire machine state. For example, restoring a package manifest and lockfile does not restore node_modules. Review the project’s dependency state if those files changed.

Next steps