Troubleshooting
Symptom-first fixes for the problems studios actually hit, grouped by where you see them. Two tools help with almost everything here: the Bridge tab in DousenDesktop (is the app connected? did the event go out?) and the Logs tab (what did Dousen just do?).
Where logs and config live
| What | Where |
|---|---|
| Desktop log | The Logs tab in the main window (also printed to the terminal if launched from one). There is no log file on disk. |
| Desktop config | %APPDATA%\Dousen\DousenDesktop\config.ini on Windows, ~/.config/Dousen/DousenDesktop/config.ini on Linux. |
| Bridge token | bridge.token next to the app data — %APPDATA%\Dousen\DousenDesktop\ (Windows), ~/.local/share/Dousen/DousenDesktop/ (Linux). Regenerated on every DousenDesktop start. |
| Blender addon log | dousen_blender_bootstrap.log in your temp directory — written even when Blender has no console. |
| Other DCC addons | They print [Dousen] … lines to the DCC's own console (Maya Script Editor, MAXScript Listener, Houdini console, Substance log). |
| Unreal plugin | The editor's Output Log under the LogDousenUE category (and the project's Saved/Logs/). |
Set the environment variable DOUSEN_DEBUG=1 before launching a DCC to make the addons print errors they would otherwise swallow. Addons deliberately fail quiet so a pipeline hiccup never blocks an artist — debug mode turns the noise back on.
The Dousen panel doesn't appear in my DCC
- Launch from DousenDesktop, not a desktop shortcut. The addon is injected at launch time; a DCC started on its own has no Dousen panel. See DCC addons.
- Check the executable entry in Settings → DCC Apps. The entry's type must resolve to the real application — for example, pointing Blender's entry at
blender-launcher.exeis handled, but a hand-added entry with an unrecognized id launches the app without any addon. - Read the DCC's console. A failed load prints
[Dousen] Failed to load <dcc> addon: <error>. For Blender, checkdousen_blender_bootstrap.login the temp directory instead. - Relaunch with
DOUSEN_DEBUG=1if the console shows nothing at all.
Bridge problems
"Bridge not available." when publishing
The addon retries a publish three times with backoff before giving up with this message. In order:
- Is DousenDesktop actually running? The bridge lives inside it — quitting the tray app stops the relay.
- Was DousenDesktop restarted after the DCC was launched? That's fine — the addon re-reads the bridge token on every request — but if the relay port was changed in Settings, running DCCs keep the old port until relaunched.
- Check the Logs tab for
[BridgeRelay] Failed to listen on port 8766. Another program holding the port prevents the relay from starting; change the port under Settings → Connection → Bridge and relaunch your DCCs.
A DCC shows as disconnected even though it's open
Connected apps must re-announce themselves every 10 seconds; the relay drops anything silent for 30 seconds. A DCC that is frozen (long render, modal dialog blocking its event loop) will drop off the badge and come back on its own. The addons also reconnect automatically with backoff (1 s doubling to 32 s), so a brief relay outage heals itself.
Events published but nothing happens in the receiving app
- Confirm the event reached the relay: it should appear in the Bridge tab event timeline.
- Events carry an optional target — a Send to Painter with Painter closed goes nowhere. Check the receiving app is on the connected list.
- The relay keeps the last 200 events; an app that was closed during a publish won't see it after reopening. Publish again.
Jira problems
| Symptom | Fix |
|---|---|
| "Jira sign-in failed — check your Jira email and API token in Settings." | Jira rejected your credentials (401/403). Re-enter the account email and a fresh API token from your Atlassian account, then use Test Connection in Settings → Jira. Polling resumes once the test passes. |
| "Offline — can't reach Jira…" banner | Network problem, not credentials — wrong base URL, VPN, or no connectivity. Polling backs off (60 s, then 5 min) and recovers by itself when Jira is reachable again. |
| "✗ Fill in all Jira fields first" in the test dialog | Base URL, email, and token are all required. The base URL is your full Jira Cloud site, e.g. https://yourstudio.atlassian.net. |
| Task list is empty but you have work assigned | My Tasks only shows issues assigned to you that are not in a Done status category. Check the assignee on the issues in Jira. |
Sign-in and session problems
"Session active on another device. Please log in again."
Dousen allows one active device per account. Signing in on a second machine ends the first session — this notification means another sign-in (yours or someone using your account) took over. Sign in again to reclaim the session; if you didn't sign in elsewhere, tell your admin.
"Session expired. Please sign in again."
The background token refresh failed — usually after a long offline period or a server-side sign-out. Signing in again fixes it. If it repeats immediately, the server may be unreachable: use Test Connection under Settings → Connection.
Perforce problems
| Symptom | Fix |
|---|---|
| "Failed to start p4. Is it installed and on PATH?" | Onboarding and the DCC lock features shell out to the p4 command line. Install the Helix command-line client and make sure p4 resolves in a terminal. |
| "P4: not connected" in the status bar | The configured P4 server is unreachable or the workspace is wrong. Check the project's P4 server/workspace under Settings → Projects. |
| "Workspace creation failed: …" | The message contains p4's own error — most often a bad depot path or a workspace name that already exists on another host. Fix the field it names and retry; you can also create the workspace in P4V and re-run the check. |
| Export blocked: "<file>: locked by <user> (CL n)" | Not an error — someone else has the file checked out, and the pre-export lock check refuses to overwrite their work. Coordinate with them or wait for their submit. |
| Files missing after onboarding created a workspace | By design, workspace creation does not sync. Sync from P4V or UnrealGameSync before working. |
Unreal Engine problems
- Assets don't auto-reimport. Check, in order:
bAutoReimportOnBridgeEventistrue; DousenDesktop is running (the plugin polls its relay); and the Output Log forLogDousenUEwarnings. "Bridge relay unreachable (failure #n)" means the desktop app isn't running or the relay port doesn't matchBridgeRelayPort. - No naming-convention checks and imports land in odd paths.
ProjectIdis empty inConfig/BaseDousenUE.ini— conventions are skipped entirely until it's set to the project's UUID. - Unreal missing from "Send to Unreal" lists. The editor must be open with the plugin loaded to appear as a connected DCC. With the editor closed, enable headless import in DousenDesktop (Settings → Unreal) so publishes still land.
Server problems (self-hosted admins)
| Symptom | Fix |
|---|---|
| Server exits at startup: "license validation failed" | The license token is malformed or doesn't match the public key. Re-paste DOUSEN_LICENSE_KEY and DOUSEN_LICENSE_PUBLIC_KEY_PEM exactly as issued. |
| Server exits: "license expired and grace period has ended" | Licenses keep working for 14 days past expiry with a warning in the logs; after that the server refuses to start. Renew and replace DOUSEN_LICENSE_KEY. |
| Creating a user fails: "Seat limit reached (n/n)…" | Every seat is in use. Free a seat or raise the plan's seat count, then retry. See User & auth management. |
| Jira webhook events never arrive | Check the webhook URL ends in /webhooks/jira, is reachable from Jira Cloud (public HTTPS), and that DOUSEN_WEBHOOK_SECRET matches the secret configured in Jira. |
Still stuck? Grab the relevant log (Logs tab, DCC console, or LogDousenUE output) and contact support — a log line almost always identifies the failure faster than a description of it.