Troubleshooting
Describes how to find the stage where a publish failed, and lists the messages Dousen shows, with their causes and fixes, grouped by where you see them.
Start with DousenDesktop’s Publish history tab, which shows the connected applications and what happened to each instance. Click Show connection events to see the traffic through the bridge, then open Logs for the detailed error.
Find the failing stage first
- Write down the project, Jira issue, source path, DCC version, Unreal project, and time of the failure. Read the error before you repeat the operation.
- Check your Desktop sign-in and project. If a DCC doesn’t launch, check its executable or addon setup. If a connected app is missing from the list, see Bridge problems.
- If validation fails, expand the rule and the affected instance. Fix the source data, or ask the project admin to review the rule.
- If the export succeeds, open Publish history. For a failed import, read Unreal’s Output Log and check the import target, the source file, and any package-save errors. For an unconfirmed import, check the asset in the engine before you retry.
- If Unreal saved the asset but the submit fails, check the Perforce changelists. If the Jira transition is missing, check the server-side Jira integration.
- When you report a problem, include the failing stage, the exact message, the source objects that reproduce it, and the relevant part of the log, with passwords and tokens removed.
For missing materials or an empty material picker, see catalog troubleshooting.
A publish exported but didn’t complete
An import is complete only when Unreal reports a saved package that matches it. For a failed result, fix the reported cause. For an unconfirmed result, check Unreal before you publish again. For retry rules and topology changes, see Recover from a failed publish and Interchange troubleshooting.
Where logs and config live
| What | Where |
|---|---|
| Desktop log | The Logs tab in the main window. Desktop also prints it to the terminal if you launched it from one. There’s no log file on disk. |
| Desktop config | config.ini in %LOCALAPPDATA%\Dousen\DousenDesktop\ on Windows, or in
~/.config/Dousen/DousenDesktop/ on Linux. |
| Bridge token | bridge.token in the app data folder: %APPDATA%\Dousen\DousenDesktop\ on
Windows or ~/.local/share/Dousen/DousenDesktop/ on Linux. DousenDesktop creates a new token
every time it starts. |
| Blender addon log | dousen_blender_bootstrap.log in your temp directory. It’s written even when Blender has
no console. |
| Other DCC addons | They print [Dousen] … lines to the DCC’s own console: the Maya Script Editor, the
MAXScript Listener, the Houdini console, or the Substance log. |
| Unreal plugin | The editor’s Output Log, under the LogDousenUE category, and the project’s
Saved/Logs/ folder. |
| Server (self-hosted) | docker compose logs -f dousen-api |
Set the environment variable DOUSEN_DEBUG=1 before you launch a DCC to make the addons print errors
that they would otherwise swallow. By default they stay quiet, so that a pipeline problem never blocks an
artist.
The Dousen panel doesn’t appear in my DCC
- Launch the DCC from DousenDesktop. Desktop injects the addon every time it launches the DCC, so a DCC that you start from a desktop shortcut has no Dousen panel. Dousen doesn’t register through the DCC’s own addon manager, such as Blender’s Preferences → Add-ons, so there’s nothing to enable there. See DCC addons.
- Check the executable entry in Settings → DCC Apps. The entry’s type must resolve to the real
application. Desktop handles an entry that points Blender at
blender-launcher.exe, but a hand-added entry with an unrecognized id launches the app without an addon. - Read the DCC's console. If the addon fails to load, Maya, 3ds Max, and Houdini print
[Dousen] Failed to load <dcc> addon: <error>. Blender prints[Dousen] Failed to register addon: <error>and also writes it todousen_blender_bootstrap.login your temp directory, which helps when Blender has no console. - Relaunch with
DOUSEN_DEBUG=1if the console shows nothing at all.
Older DousenDesktop builds could fail to load the Maya, 3ds Max, and Blender addons with no console output, even with debug logging on, because Dousen’s bundled Python modules hid the DCC’s own standard library modules. If tools are missing and the console is silent, update DousenDesktop.
Bridge problems
"Bridge not available." when publishing
The DCC panel shows this when Desktop’s bridge didn’t confirm the request. Dousen sends a publish request only once, because the server may already have accepted it, so check Publish history before you publish again. Then check these, in order:
- Is DousenDesktop running? The bridge runs inside it, so quitting DousenDesktop stops the relay.
- Did you change the relay port? Restarting DousenDesktop while a DCC is open is fine, because the addon reads the bridge token again on every request. But a DCC keeps the relay port it launched with, so relaunch running DCCs after you change the port in Settings.
- Does the Logs tab show
[Bridge] RPyC service failed to bind on port 8766 - reverting to stopped? Then another program holds the port. See the first row of the table below.
| Message | Cause | Fix |
|---|---|---|
Desktop Logs: [Bridge] RPyC service failed to bind on port <n> - reverting to stopped |
Another program is using the relay port, so the bridge didn’t start. | Change the port in Settings → Connection → Bridge (the Bridge relay port field) and relaunch your DCCs. |
Desktop Logs: [RPyC] Bridge failed; check pinned dependencies and port |
The bridge’s Python service failed to start. | Check that the relay port is free (see above). If it is and the message persists, update or reinstall DousenDesktop. |
Unreal Output Log: Bridge registration failed (<status>) or
Bridge publish unconfirmed (<status>) |
The Unreal plugin couldn’t reach DousenDesktop’s bridge. Status 503 means the request
failed. |
Start DousenDesktop, and check that BridgeRelayPort matches Desktop’s relay port. |
Unreal Output Log: The RPyC bridge requires a loopback host |
BridgeRelayHost in Config/DefaultDousenUE.ini isn’t localhost,
127.0.0.1, or ::1. |
Set BridgeRelayHost back to localhost, because the bridge always runs on the
artist’s own workstation. |
A DCC shows as disconnected even though it’s open
DCC addons and the Unreal plugin renew their registration with DousenDesktop regularly. The addons renew every 10 seconds, and Desktop drops a registration that isn’t renewed within 90 seconds. So a DCC that freezes, for example during a long render or behind a modal dialog, leaves the connected list and comes back when it responds again. If the relay connection drops, the addons reconnect on their own. They wait 0.1 seconds before the first retry and double the wait up to 2 seconds.
Events published but nothing happens in the receiving app
- To check that the event reached the relay, click Show connection events in Publish history.
- An event can name a target app, so a Send to Painter with Painter closed goes nowhere. Check that the receiving app is in the connected list.
- Live events go only to the apps that are connected when the event is published. An app that was closed then doesn’t get the event later, and the relay keeps only the last 200 events as history. Check the publish state and the destination before you publish again.
A custom tool shows stale task context after Desktop restarts
Custom tools connect through the bundled BridgeClient, which handles the bridge token. After Desktop
restarts, discard any task context your tool cached and wait for a new task.context event. See
Bridge API.
A long-running DCC session ignores a convention or setting change
Addons cache the project’s conventions and pipeline settings for 5 minutes, so a change can take that long to arrive.
If it still doesn’t arrive, check the addon’s credential. DousenDesktop launches each DCC with
DOUSEN_CREDENTIAL_FILE and DOUSEN_CREDENTIAL_ID, and the addon reads the current access
token from that file for every request. DOUSEN_TOKEN is used only when neither variable is set, for
explicit or self-hosted launches.
- If DousenCore can’t be reached, the addons keep using the last values they fetched.
- If the credential file is missing, expired, or belongs to a different studio, the addons send no token, drop their cached values, and use defaults until the credential is valid again. Sign in to the right studio in Desktop, relaunch the DCC from Desktop, and collect again before you publish.
Working offline
When DousenCore is unreachable, DousenDesktop queues two kinds of operations on disk: source-asset metadata upserts (what an artist published from a DCC) and changelist opens that go through the server route. They’re sent automatically when the server answers again. Submitting a changelist and the Jira sync need a live connection. Desktop drops a queued item that the server rejects with a 4xx response, and it clears the queue when you sign out. See Working offline.
The offline queue is a preview feature. Treat it as best-effort, and don’t assume that every action is safe during an outage.
If Desktop hasn’t reached DousenCore for 14 days, the queue stops accepting new work and shows "Offline too long — reconnect to Dousen to verify your license before more changes can sync." Reconnect before then if you can.
Validation and export problems
These messages appear when an export or publish won’t go ahead. For the rules themselves, see Asset validation. The Publish tab (Maya, 3ds Max, Substance Painter, Substance Designer) validates and then exports when you click Publish.
| Message | Cause | Fix |
|---|---|---|
| "Publish stopped: fix validation errors before exporting" (Publish tab log) | At least one checked instance has an error-severity result, so Publish validated and then stopped before it exported anything. | Expand the failing results, fix the objects or use Fix, then click Publish again. |
| "N warning(s) found. Publish anyway?" | The checked instances have only warnings. The default answer is No. | Choose Yes to publish through the warnings. If you choose No, the Publish tab shows "Publish cancelled — N warning(s) unresolved" and exports nothing. |
| "Files locked by another user" or "Files locked: …" | Another Perforce user has locked a file that the export would write. | See Perforce problems. |
| A rule is stricter, looser, or missing compared with what you remember | Your project’s naming convention can turn on a rule that’s off in the baseline, change a warning to an error, or tighten a parameter such as the triangle budget or texture limit. | Ask your admin to check the effective rule set on the project’s Validators tab in the web portal. |
To see what an artist ran into, open Validation history in the portal, or ask for the results in their Dousen panel. For the rules that run, see Which rules run.
Jira problems
| Message | Cause | Fix |
|---|---|---|
| "Jira sign-in failed — check your Jira email and API token in Settings." | Jira rejected your credentials (401 or 403). Desktop pauses task polling. | Enter the account email and a new API token from your Atlassian account in Settings → Jira, click Test Connection, and save. Polling resumes when you save Settings. |
| "Offline — can't reach Jira (<reason>). Retrying automatically." | A network problem, such as a wrong base URL, a VPN, or no connection. | Nothing to do. Polling backs off (60 seconds, then 5 minutes). When Jira is reachable again, Desktop shows "Connection restored." |
| "✗ Fill in all Jira fields first" in Settings (or "Fill in all Jira fields first." in onboarding) | The Jira base URL, email, and token are all required. | Fill in all three. The base URL is your full Jira Cloud site, for example
https://yourstudio.atlassian.net. |
| "✗ Failed" after Test Connection | Jira didn’t answer HTTP 200 within 5 seconds. | Check the base URL, the email, and the token, and check that you can reach Jira from this machine. |
| The task list is empty but you have work assigned | My tasks shows only the issues assigned to you that aren’t in a Done status category
(assignee=currentUser() AND statusCategory != Done). |
Check the assignee and status of the issues in Jira. |
Sign-in and session problems
| Message | Cause | Fix |
|---|---|---|
| "Session active on another device. Please log in again." (tray notification) | Dousen allows one active device per account, and another sign-in, by you or someone using your account, took over the session. The old device keeps working until its next 60-second heartbeat or token refresh, so the two can overlap for up to a minute. | Sign in again to take the session back. If you didn’t sign in anywhere else, tell your admin. |
| "Session expired. Please sign in again." | The background token refresh failed, usually after a long time offline or a sign-out on the server. | Sign in again. If it keeps happening immediately, the server may be unreachable. Click Test Connection in Settings → Connection. |
| "Sign-in timed out. Please try again." | Sign in with Browser got no callback for 5 minutes, for example because you closed the tab. | Click Sign in with Browser again. Desktop doesn’t leave a listener open afterward. |
| "Login failed" in the browser tab | The browser’s callback to Desktop was invalid or reported an error, for example because the server rejected the authorize step. | Start the sign-in again from DousenDesktop instead of reloading the browser tab. |
| "Seat limit reached — contact your administrator." on the portal sign-in page | The instance uses directory sign-in, and a new user can’t be created because every seat is in use. | Deactivate a user who has left, or ask for a license with more seats. See User and auth management. |
Sign in with Browser opens your system browser to a one-time OAuth (PKCE) flow, with a local callback listener on a loopback port that the operating system picks.
The first-run setup wizard (server, Jira, Perforce workspace, Unreal project, DCC discovery) appears only on a fresh install, and DousenDesktop skips it after it completes. To set a machine up again without reinstalling, click Re-run Setup on the sign-in screen (see Desktop app) instead of deleting config files.
Auto-update problems
| Message | What it means |
|---|---|
| "SHA-256 checksum mismatch — download may be corrupted" | The downloaded installer doesn’t match the published hash, so Desktop refuses the update. Click Retry. If it keeps failing, a proxy or CDN cache may be serving a bad copy, so download the installer manually. |
| "Update signature verification failed — the installer is not signed by Dousen. Refusing to install." | The installer’s signature doesn’t verify, so it may have been tampered with or come from an untrusted mirror. Don’t bypass this. Get the installer from the official release channel. |
| "Update manifest signature verification failed — the advertised version is not signed by Dousen. Refusing to install." | The update manifest’s own signature doesn’t verify. Get the installer from the official release channel. |
| "Manifest missing sha256 — refusing unsigned update" | The update manifest is malformed or unsigned, which is a server-side release problem. Report it. |
| "This build has no update-signing key configured; refusing to install an unverifiable update. Please download the update manually." | This build can’t verify update signatures, so it won’t install any update. Download the installer manually from the official release channel. |
In every case, Desktop refuses the update, and the dialog shows a red "✗ Download failed: …" status with a Retry button. The version you’re running isn’t touched, so a failed update never leaves you on a broken install.
Perforce problems
| Message | Cause | Fix |
|---|---|---|
| "Failed to start p4. Is it installed and on PATH?" | The onboarding workspace steps run the p4 command line directly, and Desktop can’t find it. |
Install the Helix command-line client, and check that p4 works in a terminal. |
| "Perforce server/user/workspace not fully configured — set them in Settings" | Some of the Perforce server, user, and workspace are set in Desktop, but not all three. | Fill in all three in Settings, or clear them all. |
| Status bar: "P4: not connected" or "P4: connection unavailable" | Perforce didn’t report a workspace, or the check failed. Hover over the label to see the reason for the second message. | Check the project’s Perforce server and workspace in Settings → Projects, and check that you’re signed in to Perforce. |
| "Depot check failed: …" or "Unable to determine whether the depot is a stream. Check the depot path and try again." | The Check button in the Workspace step ran p4 commands that failed. The
message includes p4's own error. |
Check the depot path, the server, and your Perforce sign-in, then run Check again. |
| "Workspace creation failed. Check P4V before retrying: …" | The message ends with p4's own error. The usual causes are a bad depot path, or a
workspace name that already exists on another host. |
Check P4V first, because the workspace may already exist. Then fix the field the error names and retry, or create the workspace in P4V and run Check again. |
| "A Perforce operation is already running." | You started a second changelist open, submit, or unshelve while the first was still running. | Wait for the first operation to finish. |
| "This changelist has no opened files. Move the intended files into it in P4V." | You clicked Submit changes, but the task’s numbered changelist is empty. Desktop doesn’t move files out of the default changelist. | Move the files you want into the task’s changelist in P4V, then submit again. |
| "Perforce timed out; the outcome may be unknown. Check P4V before retrying." or "Submit outcome is unknown. Check Perforce before retrying." | A p4 command didn’t finish or didn’t confirm its result. |
Check the changelist in P4V before you retry. Dousen recovers an interrupted open or submit through the markers in the changelist description. |
| "Multiple Perforce changes have this task marker; resolve them in P4V." | Two pending changelists carry the same Dousen task marker in their descriptions. | Delete or merge the extra changelist in P4V, then try again. |
| Export blocked: "<file>: locked by <user> (CL n)" | Someone else has the file locked, so the lock check stops the export before it overwrites their work. | Coordinate with that user, or wait for their submit. |
| Files are missing after onboarding created a workspace | Workspace creation doesn’t sync. | Sync from P4V or UnrealGameSync before you start work. |
| Status bar shows "P4: <stream>" instead of "(classic)" | This is informational. The workspace is a stream workspace. | Hover over it to see the workspace name and the server version. |
Inside a DCC, the lock, checkout, and changelist features use P4Python if the DCC’s own Python
can import it, and otherwise switch silently to the p4 command line. If neither is available, those
calls return nothing instead of an error, so lock status can go quiet without a message. If the lock rows stop
updating, see Perforce.
Unreal Engine problems
For the full plugin reference, see Unreal Engine.
| Symptom | Cause | Fix |
|---|---|---|
| Assets don’t reimport automatically | Auto-reimport is off, or the plugin can’t reach DousenDesktop’s bridge. | Check, in order, that bAutoReimportOnBridgeEvent is true, DousenDesktop is
running, BridgeRelayPort matches Desktop’s relay port, and the Output Log has no
Bridge registration failed warning from LogDousenUE. |
Output Log: Refusing to contact DousenCore over cleartext HTTP on a non-loopback host |
The plugin allows plain HTTP only to a loopback host. | Set ServerScheme=https in Config/DefaultDousenUE.ini and use an HTTPS address
for the server. |
| Naming-convention checks are missing, and imports land in odd paths | ProjectId is empty in Config/DefaultDousenUE.ini, so Dousen skips
conventions. |
Set ProjectId to the project’s UUID. If the editor has DOUSEN_PROJECT_ID in its
environment, it uses that value instead. |
| Unreal is missing from the "Send to Unreal" lists | The editor appears as a connected DCC only while it’s open with the plugin loaded. | Open the editor, or turn on headless import in DousenDesktop (Settings → Unreal) so publishes still land. See headless import. |
Server problems (self-hosted admins)
| Message | Cause | Fix |
|---|---|---|
Log:
DOUSEN_LICENSE_KEY not set and no persisted license found — Core is locked (fail closed),
or DOUSEN_LICENSE_PUBLIC_KEY_PEM not set — … locked (fail closed) |
No license is configured, so DousenCore is locked. | Set DOUSEN_LICENSE_KEY and DOUSEN_LICENSE_PUBLIC_KEY_PEM in
.env and restart. See Self-hosted install. |
Log: license validation failed — Core is locked (fail closed) |
The token is malformed, doesn’t match the public key, or expired more than 14 days ago. The
error field says which. |
Paste DOUSEN_LICENSE_KEY and DOUSEN_LICENSE_PUBLIC_KEY_PEM again exactly as
issued. For an expired license, get a renewed key and restart. |
Log: DOUSEN_LICENSE_PUBLIC_KEY_PEM is not a valid PEM public key (…) — Core cannot verify any license and is
locked (fail closed) |
DOUSEN_LICENSE_PUBLIC_KEY_PEM isn’t a valid PEM public key, so Core starts locked. |
Paste the key again exactly as issued, inside double quotes. See Self-hosted install. |
Log: LICENSE EXPIRED — operating in grace period. Renew at https://dousen.io/billing |
The license expired, but the server is inside its 14-day grace period. It keeps running and logs the remaining days at each startup. | Renew before the grace period ends. The portal has no countdown, so watch the logs. |
Log:
license expiry recheck failed: license expired and grace period has ended … — Core is now locked |
The grace period ended while the server was running. DousenCore checks the expiry every hour. | Put a renewed DOUSEN_LICENSE_KEY in .env and restart. |
Log: license <revoked|cancelled|suspended> by control plane: … — Core is now locked |
The control plane rejected the license heartbeat with a JSON 403. | Resolve the cause with Dousen billing, for example a payment or a seat overage. A locked instance
retries every hour. After revoked or cancelled, Core remembers the lock across
restarts, so you need a newly issued license. |
Log: license heartbeat got a 403 that isn’t a control-plane verdict |
A proxy or firewall blocked the heartbeat. Core stays in its current state and tries again at the next heartbeat. | Allow the instance to reach DOUSEN_CONTROL_PLANE_URL, or set it to empty to turn the heartbeat
off. |
Requests return 403 with "code": "unlicensed" and "Dousen Core is unlicensed: …" |
DousenCore is locked. /health still answers, so the container looks healthy. |
Read the reason after "unlicensed:" and find the matching log line above. |
Log: JWT secret must be at least 32 bytes, got N (the container restarts repeatedly) |
DOUSEN_JWT_SECRET is shorter than 32 bytes. |
Set a random value of at least 32 bytes, for example openssl rand -hex 32. |
| "Seat limit reached (n/n). Upgrade your plan to add more users." | Every seat is in use, and pending invites count. | Free a seat with Deactivate or Remove, or get a license with more seats, then try again. See User and auth management. |
| Users page: "<email> was created, but SMTP isn't configured on this instance — no email was sent." Or, after Send reset link: "SMTP not configured — no email sent. The link is logged only at debug level" | No mail server is configured, so Dousen can’t email the link. The invite or reset itself worked. | Configure SMTP, or take the link from the log at the debug level with RUST_LOG=info,dousen_api::email=debug. See
Self-hosted install. |
| Jira webhook returns 401 | The signature didn’t verify. The secret in Jira’s webhook doesn’t match DOUSEN_WEBHOOK_SECRET. |
Copy the secret again on both sides. |
| Jira webhook returns 503 | DOUSEN_WEBHOOK_SECRET isn’t set, so the server refuses unsigned webhooks by default. |
Set the secret. For development only, DOUSEN_ALLOW_INSECURE_WEBHOOK=true turns the check
off. Never use it in production. |
If you’re still stuck, contact support and include the relevant log: the Logs tab, a DCC console,
or the LogDousenUE output.