# Publishing Troubleshooting

> Fixes for the most common GitHub publishing problems in Edit Mode — OAuth setup, disconnects, a disabled Publish button, merge conflicts, and missing assets.

- Source: https://diceytable.com/docs/mods/publishing/troubleshooting
- Last verified: 2026-07-27

## "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.

## See also

- [Connect GitHub](https://diceytable.com/docs/mods/publishing/github-setup)
- [The Publish Flow](https://diceytable.com/docs/mods/publishing/publish-flow)
- [Registration & Multiplayer Play](https://diceytable.com/docs/mods/publishing/registration-and-play)
