Publishing Troubleshooting
"GitHub publishing is not configured on this server"#
Connect GitHub returns a 503 with this message when the server it's talking to hasn't been given a GitHub OAuth App to use. This is a one-time, server-side setup — nothing an individual author can fix from the editor.
The server needs four environment variables, all unset by default:
GITHUB_OAUTH_CLIENT_ID=<client id>
GITHUB_OAUTH_CLIENT_SECRET=<client secret>
GITHUB_OAUTH_CALLBACK_URL=http://127.0.0.1:8787/api/editor/github/oauth/callback
GITHUB_OAUTH_WEB_ORIGIN=http://127.0.0.1:5173
These come from a GitHub OAuth App (Settings → Developer settings → OAuth Apps →
New OAuth App), requesting the repo scope, with its callback URL pointed at
/api/editor/github/oauth/callback on the server you're running. If you're standing up
your own DiceyTable deployment, add these to the server's environment (locally, in
apps/server/.env); if you're seeing this on a hosted deployment you don't control,
it's a configuration gap to report to whoever runs it.
This is a different GitHub integration than the GITHUB_TOKEN environment
variable — that one is optional and only raises the mod scanner's API rate limits; it
has nothing to do with OAuth publishing and won't fix this message.
"Connect your GitHub account before publishing" after it worked a minute ago#
If a checkpoint or publish suddenly fails claiming you're not connected, but the Publish dialog still shows "Connected as @you", trust the error, not the label. The server clears a stored GitHub token the moment any GitHub API call comes back unauthorized (a revoked or expired token) — but the editor only re-checks your connection status when the Publish or New Mod dialog is opened. If a token was cleared while that dialog was already open, the on-screen "Connected" state can be briefly stale.
Fix: close and reopen the Publish dialog (this re-fetches your real status), then click Connect GitHub again. You'll get a fresh popup and a fresh token; nothing about your mod or its repository link is lost.
Publish button is disabled#
Publish is gated on the same discovery requirements as the mods library. Open Mod Details and check for a missing title, summary, square cover image, or screenshot — the dialog lists exactly what's missing. A repository must also be linked (or entered inline if the project has none yet) before the button becomes clickable.
"There is a merge conflict" when publishing#
Publish's final step merges wip into main on GitHub. This fails if main has
commits that wip doesn't already contain — most commonly because someone edited a
file directly on GitHub (through the web UI, or a separate git push) instead of
through the editor. Resolve it in GitHub directly (or on main's history), then
publish again from the editor; there's no in-editor conflict resolver.
Linked an existing repository and nothing works for other players#
The editor does not check the visibility of a repository you link yourself (as opposed to one it creates for you, which is always public). If you linked an existing private repository, you can still author and preview the mod alone — but the public-facing pieces of the pipeline (the scanner's anonymous fetch at registration, and every other peer's anonymous asset pull at play time) will fail for anyone except you. Make the repository public, or transfer the mod's files to a public one, before asking anyone else to join.
Some assets didn't come down#
A play-time asset pull never fails all-or-nothing — each file downloads independently, and one file's failure (dropped connection, renamed/missing file on the branch that was registered) doesn't stop the rest. When this happens you'll see a status message naming how many assets failed, and the table still opens with everything that succeeded. Reloading the table retries the pull; anything already cached from a prior successful pull is skipped, so a retry is cheap.
I published, but players still see the previous version#
Publishing does three things: it pushes the tree, merges it to main, and re-scans
the published repo. Only the third rewrites the mod's library listing and, with it,
the content version every player's local cache is keyed on. If the re-scan fails,
Publish now reports it as an error rather than a footnote — the bytes are on GitHub but
the listing and every cached copy still describe the previous version. Publish again to
retry it.
If the re-scan succeeded and a player still sees old art, have them reload once. Their
cache is keyed on the new version, so the reload re-downloads rather than reusing the
old scope. A second reload will not help — if it's still wrong, the mod's version did
not change, which means the re-scan found identical content (check that your changes
actually reached main).
Assets render as plain placeholder boxes#
This is the visible symptom of an asset reference that hasn't resolved to a loadable
URL yet — most often because the local pull cache is still priming when the object
first tries to render, or because a repo-relative asset path failed to download and
there's no configured remote fallback for it (a legacy, pre-local-first mod referencing
assets by an opaque server-side id rather than a repo path). For a currently-loading
table, give the loading screen's asset-download step a moment to finish. If placeholders
persist after the table finishes loading, check the browser console for pull failures
and confirm the asset actually exists at that path on the mod's main branch.
Local storage isn't available in this browser#
Local-first authoring and the play-time pull cache both need either the origin-private file system (OPFS) or, as a fallback, IndexedDB. If neither is available, opening a project's local files (or pulling a mod's assets at play time) fails outright rather than silently degrading. This is rare on current desktop and mobile browsers, but worth ruling out if a specific browser or embedded webview behaves differently from everything else you've tested on.