Drawbridge

Troubleshooting

Most surprises in Drawbridge are a feature behaving as designed. This page lists the ones people hit first, and what is actually going on.

Connectors keep moving when I move something else

That is the router doing its job. Auto connectors have no stored geometry — the whole page is re-solved whenever the obstacle field changes, so moving one device can change the cheapest path for a connector that has nothing to do with it.

If a specific cable must never move, select it and set its type to Direct (a straight line) or Custom (your own waypoints). Both are stored geometry that the router never touches. See Connectors.

A connector runs straight through a zone or a rack

Only devices are obstacles. Zones, racks, virtual contexts, map underlays, text and callouts are deliberately transparent to routing — a cable through a zone boundary is usually exactly what the diagram means.

A connector attached to a zone or rack is a straight line

Connectors that land on a container skip the router and are drawn centre to centre. Attach the cable to a device inside the container if you want a routed path.

Parallel links between the same pair are fanned sideways so you can see and click each of them. That fan is derived, not stored, and is stable across saves. To make them one logical bundle instead, select them and press Bind as aggregate in the inspector's Aggregate section.

Devices I moved into a rack snapped somewhere else

A device whose centre lands in a rack's usable area snaps to a U boundary and centres horizontally — racks own the positions of what is mounted in them. Align and even-spacing skip rack units for the same reason. Drag it back out of the rack to place it freely.

A page opens empty and its tab says "read-only"

Compressed legacy draw.io pages open as ordinary editable pages — Drawbridge decompresses them. A tab marked "Unreadable page — read-only" is one whose payload could not be decoded at all: a damaged file, or compression draw.io never wrote. Its original XML is preserved verbatim so saving cannot destroy it, and the other pages in the file open normally. Re-save the file with a current draw.io — it writes uncompressed by default — and open it again. See Files and templates.

My Visio file lost things when it opened

.vsdx is an interchange path, not an archival one. 2D shapes become devices — keeping their embedded picture when they have one — and 1D connector shapes become links, even when a line was never glued (an end that touches a device connects to it) or lives grouped with its caption. Plain text boxes arrive as text. What is dropped: guides, decorative divider strokes, and Visio-only content like themes and data graphics; a shape the catalog cannot name arrives as a generic device rather than disappearing. Nothing foreign is preserved from a .vsdx, unlike .drawio, where unmodelled content is written back untouched.

The Save button says "Saving…" and there is no Save dialog

That is auto-save. Once the document is bound to a file, edits are written back automatically and the button becomes status. Turn it off under App menu → Auto-save if you prefer saving by hand.

"Auto-save paused — click to re-enable"

The browser revoked write permission for the file handle. Re-requesting it requires a user gesture, so the app will not prompt from a background timer — click the toast once and auto-save resumes. In the desktop app this only appears if a write genuinely failed.

I saved in the browser and nothing was written back afterwards

Save writes back to the file on disk only where the browser offers the File System Access API, and only there does auto-save to disk exist. Without it, Save is a plain download — a new file in your Downloads folder every time — and the document stays marked unsaved on purpose, because the browser never reports whether the download completed or was cancelled. The local snapshot still restores your work on the next visit.

Where you get a download instead of save-in-place:

For a file on disk that stays bound and auto-saves, use Chrome or Edge on the https:// site, or the desktop app, which uses native dialogs and needs no browser API. A cloud storage connected under Storage… is unaffected — that path never uses the File System Access API and saves in place in Firefox too. See Files and templates.

Save as in Firefox or Safari did not let me choose the folder

A web page cannot choose where a download goes in Firefox or Safari, and those browsers have said they will not add the API that lets it. What the app can ask, it asks: the first time you save a drawing, and every time you choose Save as…, a small sheet asks the file's name. End the name in .vsdx to save in Visio format. A plain Save after that downloads under the same name without asking.

The folder is the browser's own setting:

The sheet says which of these applies, under the name. Chrome or Edge on the https:// site, and the desktop app, open a real save dialog instead, with the folder in it.

My exported PNG is missing a layer

Hidden layers are never exported, in any format. That is intentional — a layer you switched off cannot be recovered by whoever you send the file to. Switch the layer back on in Layers before exporting.

Copy image did nothing

Clipboard image writes need a focused window and browser support for writing images. If either is missing you get a message; click into the window and try again, or export a PNG instead.

The PDF came out white when I am working in dark mode

A PDF is always white paper with no background fill, and the drawing on it always prints the light colours. The Theme option in the export popover does not reach it: the dark colours on white paper come out as near-black tiles and cables you can barely see. Export SVG or PNG if you want the dark picture in a file.

Text I type on the canvas triggers shortcuts

It should not — canvas shortcuts are suppressed while focus is in a text field, an inspector input or the inline label editor. If a key acted on the diagram, focus was on the canvas; click into the field first.

Nothing happens when I press a shape in the palette

Clicking a palette shape arms it — the button stays lit and the next canvas click places it. Click the button again, or press Escape, to disarm. You can also drag straight from the palette onto the canvas.

A device is drawn with a dashed outline

Somebody has marked it planned: the inspector's Status row, under Network, has Planned lit for that device. Press Installed (or Not tracked) and the tile draws solid again. A device nobody has ever marked is not tracked — neither installed nor planned — and draws solid, so opening an older drawing never turns it into a wall of proposals. See Asset data.

A shape from someone else's file looks generic

Unknown shape kinds always render, falling back to the Generic shape rather than vanishing. The rest of the node — label, position, connections, asset data — is intact.

I cannot find a toolbar button

At narrow window widths the toolbar moves its trailing groups into the More (☰) overflow popover. Widen the window, or look in there.

Before it moves anything, it drops the Drawbridge wordmark next to the logo and keeps only the mark — losing a word costs you nothing, where a button in the ☰ menu costs a click every time you use it. So a bar showing just the shield is simply a narrow window, not a different build.

Sharing is missing

Collaboration works in the desktop app and in the browser. If you cannot see Share… in a browser, check the address bar: it only appears on https:// (or localhost). A self-hosted instance served over plain http:// hides it, because the browser withholds the encryption the invite handshake needs on an insecure page. See Working together.

Someone cannot join my session

Check, in order: are you still hosting (sharing ends when the window closes)? Did you Regenerate the invite, or Reset the personal link, after sending it? Are they waiting in the lobby for you to Allow? Is their Drawbridge older than the link version? Each failure is reported by name in the join dialog.

If the first few people walked in and this one has to knock, nothing is broken: either Let anyone in has run out — it lasts twenty minutes and then the lobby is back — or they are using the personal link, which always knocks. See Approval and the lobby.

Sharing will not connect

An internet session needs one thing from the network: outbound TCP on 443 to drawbridge.fortiknight.com, with the WebSocket upgrade allowed on /relay. That is an HTTP/1.1 request carrying Upgrade: websocket (subprotocol iroh-relay-v2), and it stays open for the whole session. An explicit proxy or a web filter that strips the Upgrade header, or refuses long-lived connections, breaks sharing while the rest of the app — which is ordinary HTTPS — goes on working, so "the site loads but Share never connects" points here. Whether TLS inspection with a company CA also breaks it has not been established; if your network inspects TLS and sharing fails, an inspection exemption for drawbridge.fortiknight.com is the thing to try.

In the desktop app, outbound UDP on high, changing ports is what lets two desktops connect directly. It is optional: with UDP blocked, the session still works through the relay and the pill shows relay.

Nothing inbound is needed for an internet session — every connection starts from your machine. What the network has to allow has the whole list.

Nobody can reach my LAN-only session

A LAN session is the one case where your machine has to accept a connection rather than make one, so the host firewall is the first thing to check — macOS and Windows both prompt the first time, and a Windows network marked Public blocks it. There is no port to add: the port changes every session, so what you allow is the Drawbridge application itself.

After that it is the network between you: client or AP isolation on a guest Wi-Fi, a private VLAN, or being on different subnets will all stop it. If the two machines cannot ping each other, this cannot work either. Broadcast and multicast settings are not involved — Drawbridge does no discovery; a LAN-only session dials the addresses in its LAN invite. What the network has to allow covers all of it.

A collaborator's cursor is invisible

Presence is per page — you only see people who are on the same page as you. The pages bar shows who is where.

Check for updates says it cannot reach the update feed

You are offline, the feed is blocked, or there is no published artifact for your platform on that release. Update checks are notify-only and entirely optional; nothing else in the app needs the network.

Checks lists things I have not done yet

That is its job. Checks reads the page you are on and lists what looks unfinished or inconsistent, each with a way to fix it. It runs as you draw and never stops you saving — a finding is a question, not an error. In Studio, press Checks at the top of the window (the segment carries the count) and Draw to come back; in Classic, switch Checks on in Edit layout and it docks on the right.

What it looks for:

The chips along the top — All, Cabling, Addresses, Names, Missing data — filter the list, each with its count. Ignore stops listing one finding. It is saved in the file, so it holds for whoever opens it next, and it lasts until what the finding is about changes: a fourth device with no serial is a new finding. The foot of the list counts what is ignored on the page, and Show them again brings it all back.

Ignore all, at the end of the chips, ignores every finding listed — under All that is everything, under a chip only that group, and the button then reads Ignore these. It is one ⌘Z (Ctrl Z), and a finding that appears afterwards is listed as usual: Ignore all quiets what is there now, not the checks themselves.

If you would rather not have Checks at all, Studio's Checks view has Turn Checks off: the Checks segment and its count leave the top of the window and the checks stop running. It is a setting of this computer, not of the drawing. ☰ → Preferences → Show Checks brings it back. In Classic, Checks is a panel you switch on or off in Edit layout.

Still stuck

Use App menu → Report a bug. It writes the report for you — your description plus the version, the build and the last things you did — copies it to the clipboard and opens the feedback form to paste it into. If you attached screenshots, it also saves a drawbridge-bug-report.zip to your downloads; the form has a file field for it. See Reporting a bug in Settings, desktop and privacy.

The About box (the app name at the far left of the toolbar) has the version, build date and the bundled libavoid commit, if you would rather quote them yourself.

The browser app seems to be on an old version

It should offer Update available — Reload on its own. If you think you are behind anyway, a hard refresh (⇧⌘R on macOS, Ctrl+F5 on Windows/Linux) forces the browser to discard the cached app and fetch the current one. About shows the version you are running.