Troubleshooting

The recoveries for the situations readers actually hit. The universal reset: create a fresh project from the demo (on /projects, click New project → Demo project) or create a blank project and start drawing.

A viewer is empty

The flow or deployment viewer shows an empty state in a fresh browser — is something broken? No. A fresh browser has no project yet, so every diagram screen shows a Create a project card until you create or open one. The card opens the same New Project dialog as the projects hub — choose Demo project there to explore a complete model across all three diagram types, or Blank project to start drawing. The same card appears after you delete your last project.

The viewer says "loading" forever. Reload the page first. If it persists, the browser may be blocking storage (private/incognito mode with site data disabled) — CRAYON-C4 needs browser storage for anonymous work.

My work disappeared

Different browser or machine. Anonymous and free-account projects live in the browser where you made them — they don't follow you. Cloud (Pro) projects do.

Cleared browser data. That storage was the project. Restore from a JSON export if you have one — see Manage projects for making backups a habit.

Imported a file but can't see the result. Importing a file always creates a new project — it never replaces an existing one. Check the projects hub for the newly created project. (Loading the demo also creates a new project and leaves your current work alone.)

An import is refused

Imports are checked before anything is replaced — a refused file means the check failed, and the message says where. Common causes:

  • The file isn't a CRAYON-C4 project export (wrong JSON entirely).
  • The file was hand-edited and broke a reference (a diagram pointing at a deleted element).

Fix the reported spot, or re-export from the source. A refused import never half-loads: your current project is untouched.

Sign-in trouble

The sign-in page comes back without signing me in. Cancelled or failed sign-ins return you to the landing page signed out — try again. If it repeats, your browser may block third-party cookies for the sign-in service.

Signed in but my projects are missing. Check you signed in with the same identity provider (e.g. Google vs Microsoft) you used before — different providers count as different accounts even with the same email address.

An invitation won't accept. Invitations are bound to the email they were sent to. Sign in with an account carrying that address.

Diagrams look wrong

An element shows "(unlinked)" or a connection points nowhere. A cross-reference points to something deleted. Open the relevant editor and fix or remove the stale reference; the editors highlight these.

A flow folds strangely at coarser levels. Almost always a missing or wrong C4 binding on a lane — see Link flows to your C4 model.

Save and sync issues

The save pill shows "newer version on remote" — your cloud project moved (another browser or team member pushed a change). If you have no local edits, click Load latest to restore this device from the newer cloud version. If you have unsaved local edits, click Review & save — a modal titled "This project changed on the remote" appears. Choose to keep your edits, take the remote version, or combine them (picking individual conflicts) — nothing overwrites silently.

Save failed and the pill is red. First, check the error message in the pill (hover or click it). A durable failure (project was deleted, your tier lapsed, or you're offline) offers "keep as local project" — this moves your work to local storage so nothing is lost. Once you're back online or tier is restored, you can promote it back to the cloud later.

My local project got corrupted — the app routes to a recovery page explaining the issue. You can export what remains, or try restoring from a backup JSON if you have one. Reach out to support with the error details.

Update from code

I made changes in the code extractor, and I'm reviewing what lands. When you click "Update from code" on a project's detail page, you see a full review before anything changes — adds, edits, and removals listed with the option to combine with local changes if there's a conflict. Nothing is replaced silently; cancelling closes the review without touching your project.

Where next