Repository navigation
9 Common Fixes
The problems people actually hit, and what to do about them. Install-time errors (the installer stopping, Docker not reachable, port 80 taken...) are in the table on the install page.
Commands are for Linux from the folder above JunOS. On Windows, logs are files in JunOS\runtime\logs\, and "restart" means powershell .\JunOS\start.ps1 stop then start again. More on both: Manage.
Almost always the model not fitting on your graphics card. On llama.cpp, the llamacpp log says how much of her made it onto the card:
./JunOS/start.sh logs llamacpp | grep offloaded # Windows: JunOS\runtime\logs\llamacpp.err.logoffloaded 49/49 layers to GPU is what you want (the numbers depend on the model), fewer than all means part of her runs on the CPU. On Ollama it's docker exec omega-ollama ollama ps (Windows: ollama ps), and anything other than 100% GPU means the same. Pick a smaller model or free up VRAM: Performance.
The first reply after every start is always slow, the model is being loaded. Judge her on the second.
Every start prints where she landed. If it says CPU. no GPU at all, llama.cpp found no card (or ollama gave up on the card):
-
NVIDIA: the container toolkit is missing, or its device file is stale. Missing: the start says
NVIDIA card found but Docker can't use it, run the installer again and it offers to add it. Stale: ifnvidia-smiworks on the host, regenerate it withsudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yamland restart. Full steps: NVIDIA. -
AMD: llama.cpp uses Vulkan and needs no override. On Ollama, the start script sets
HSA_OVERRIDE_GFX_VERSIONfor the cards that need it, a line in.envoverrides it. AMD.
Each line on the boot screen is a real check.
-
neural-core KO: the model isn't answering. She keeps trying and lets you in once it does. After a few tries a "continue without the model" link shows up, it opens the page but chat won't work until the model is up. Still red after a minute? Look at the logs:
./JunOS/start.sh logson Linux, Logs in JunOS.exe on Windows, Step 3's output on Colab. - live2d-rig KO: her body was never extracted, you get the placeholder. See below.
- voice-synth KO: the voice service is off or down. Chat works without it, see No voice.
- lore-corpus KO: her lore file is missing, so she knows less about her own world. Reinstall or update her.
Only neural-core keeps you on the boot screen.
The checker-pattern character is a placeholder. Her body wasn't extracted from the game. Install her body later.
- Settings > Voice > Enable voice is on?
-
VOICEinJunOS/.envisn'toff? - Still nothing:
./JunOS/start.sh logs tts. The very first start downloads about 300 MB of voice weights, give it a minute. - The log says
OverflowError: Python int too large to convert to C ssize_t? An install from late October 2026 got a broken voice package. Update her (the Update button on Windows, the install line again on Linux) and start her again.
- The browser has to be allowed to use the mic. Check the little icon in the address bar.
- On a phone, use the
https://address the launcher printed and click through the certificate warning. Browsers only give the mic to HTTPS pages. - She hears you but won't answer? She thinks you're talking to someone else in the room. Turn on Hear everything in Settings > Voice.
- She keeps cutting herself off: she's hearing her own voice through your speakers. Use headphones, or turn off Interrupt her.
forgot password? on the login screen, with your email and recovery code. Details. If you still know it and just want a new one, it's in Settings > Account.
The password was accepted but it can't unlock the account's encryption key. That happens when the password was changed by editing the database directly instead of through the app. Use forgot password? with your recovery code, that puts a working key back.
A yes in words is normally enough now: when your message is an invitation, the app takes you there even if she forgets to. What it can miss is the invitation itself. It looks for English words naming the place (shop, karaoke, dinner, lunch, blackjack...), so try again naming it plainly, or use Settings > Dates > Ask her, which always counts. A "no", "later" or "tomorrow" anywhere in her answer counts as a no. If you're an admin, or have FREE_ROAM=on, Force her skips the question. More in Dates.
Working as intended. Those pages only open after she agreed to go. Ask her first, see Dates.
The karaoke service isn't running. Check KARAOKE=on in JunOS/.env, restart, then ./JunOS/start.sh logs karaoke. The first build of that service is big and takes a while.
Not a bug. She left, and the door stays shut 5 minutes the first time, doubling up to 30. Manage.
The model got stuck saying the same thing over and over. When that happens she drops the reply and tries again, up to three times, each a little more loosely; you'll see "stuck, starting over" while it does. If all four tries loop, the reply is thrown away and a message says she broke. Just send your message again. If it keeps happening, the model itself may be bad: update her, or pick a different size in the installer.
The page got past the boot screen, so the model was up then, but it stopped answering when you sent a message. Usually it crashed while starting the reply, most often out of video memory. Look at the logs: ./JunOS/start.sh logs on Linux, Logs in JunOS.exe on Windows, Step 3's output on Colab. An "out of memory" line there means the model is too big for your card: run the installer again and pick a smaller size. Anything else, open an issue with that log attached.
Something between you and her is buffering. Only happens if you put her behind your own reverse proxy or load balancer. It has to pass /api/chat.php through unbuffered.
You hit the rate limit (90 messages a minute, two open replies at a time). Wait a minute. If you're scripting her or sharing one IP with a lot of people, the limits are in webapp/api/chat.php and the nginx config.
She always runs on HTTPS, with a certificate signed by a small certificate authority your install made for itself. The browser warns until that authority is trusted on the device you're using. The installer offers to do it, and you can do it anytime:
-
Linux:
./JunOS/start.sh trust, then restart the browser. It asks for yoursudopassword. For Chrome and Firefox it needscertutil(libnss3-toolson Ubuntu/Debian,nss-toolson Fedora,nsson Arch), it tells you when that's missing. -
Windows:
powershell .\JunOS\start.ps1 trustfrom the folder aboveJunOS, and click Yes on the Windows security warning about "Jun OS local CA". Edge and Chrome stop warning after a restart. Firefox only reads that store whensecurity.enterprise_roots.enabledistrueinabout:config. - A phone, or you'd rather not: click Advanced and Proceed (Firefox: Accept the Risk and Continue). The connection is encrypted either way.
The authority can only vouch for local names and private addresses, so trusting it doesn't let it vouch for any real website. When her address changes (new wifi address, new BIND_ADDR) she makes a new certificate with the same authority, so a trusting computer doesn't notice. If the launcher says the local CA changed, run the trust command again. The uninstaller takes it back out.
Expected for the first minute or so on a fresh prod install. The web server starts on a temporary self-signed certificate so Let's Encrypt can reach it, and switches to the real one by itself once it's issued, no restart needed. If the warning is still there after a few minutes, run ./JunOS/start.sh logs certbot: it says why. Almost always the domain doesn't point at this machine yet, or port 80 isn't reachable from the internet. It keeps retrying on its own (after 1, 4 and 16 minutes, then hourly), so fix that and wait.
The update checker found a release ending in -security, newer than yours. It fixes something serious, the link it prints says what. Update her (the Update button on Windows, the install line again on Linux) and start her again. If she was already running from before, she still is, so stop her until you've updated. Can't update right now? ./JunOS/start.sh --ignore-security (Windows: powershell .\JunOS\start.ps1 -IgnoreSecurity) starts her anyway, at your own risk.
The Jun OS window still says Running after Stop, or the uninstaller says access to caddy.exe (or php.exe) is denied. Something she started is still running without being on her list. Open Task Manager (Ctrl+Shift+Esc), end every caddy, php, python and llama-server running from the JunOS folder, then press Stop or run the uninstaller again. Versions after 1.0.8 find and end those by themselves on Stop.
The start stops with listen tcp 127.0.0.1:8080: bind: An attempt was made to access a socket in a way forbidden by its access permissions, while the Jun OS window may still say Running and the browser shows SSL_ERROR_RX_RECORD_TOO_LONG or a page that isn't hers. Another program already uses port 8080, often an older Jun OS from a different folder or some other local web server. Versions after 1.0.8 name it in the error (port 8080 is taken by ...). To find it yourself, run this in PowerShell:
Get-NetTCPConnection -LocalPort 8080 -State Listen | ForEach-Object { Get-Process -Id $_.OwningProcess } | Select-Object Id, ProcessName, PathClose that program (or end it in Task Manager) and press Start again. If you want to keep it, give her another port instead: add JUN_PORT=8090 to JunOS\.env and start her again, she's then at https://127.0.0.1:8090. If the command finds nothing, Windows itself reserved the port (Hyper-V, WSL and Docker Desktop do that, netsh interface ipv4 show excludedportrange protocol=tcp lists the ranges): pick a JUN_PORT outside them.
The app's start screen says why:
-
Can't reach: the phone has to be on the same wifi, and Jun OS has to be running on the PC. Then run
./JunOS/start.sh phoneagain (on Windows press Phone) and scan the new code: the PC's address may have changed. Turn off any VPN on the phone, most of them send local traffic through the tunnel too. On Windows, if it says it couldn't add the firewall rule, run the command it prints in an admin PowerShell. On Fedora or Bazzite,start.sh phoneoffers to open https in the firewall. If you said no, run it again, or run thesudo firewall-cmdline it prints. -
LAN mode is off: run
./JunOS/start.sh phone(on Windows press Phone), it asks to turn it on. - Doesn't know this phone anymore or has a new certificate: the key or her certificate changed on the PC. Scan a fresh code.
- Can't reach the notebook (Cloud): the Colab session ended or Step 3 ran again. Run Step 3 and scan the new code. Started from the app with Start Colab session? Pressing Stop on its notification ends the session. Battery savers on some Xiaomi, Samsung and OnePlus phones kill it too: set Jun OS to unrestricted battery use. Free Colab stops any session after about 12 hours.
Every start prints a bridge: line:
- no readable save found: the game hasn't saved yet. Play and save once.
-
no GAME_SAVE_DIR folder:
JunOS/.envpoints at the wrong folder. Run the installer again with the bridge on. - nobody paired yet: start the game once and sign in when it asks.
- events held back until the next sign-in: that's normal. Her memory is locked under your login, so what happened in the game gets written the next time you sign in or chat.
-
save NOT written: save_not_writable (Linux): Jun OS can't write the save folder.
chmod -R g+won it fixes that. With the game open the write is skipped on purpose.
Press F8 in the game to sign in: email, Next, then password and Sign in. The email popup has Insert @ if the game ignores your keyboard's @ combination; keyboard paste works too. A 401 or 403 from chat, history, voice or pairing opens it automatically and retries once after sign-in. If the game cannot reach her, start Jun OS first, then the game. If you changed her port, or the MelonLoader console shows a certificate error, run ./JunOS/start.sh bridge (Windows: powershell .\JunOS\start.ps1 bridge) and restart the game. On the native Linux game, start it through junos-game.sh (see Game bridge), otherwise the mod never loads.
Game goes black and closes right after the title card with MDRG-ModSettingsMenu installed? JunBridge 0.1.0 clashes with it, update to 0.1.1.
For native Linux startup crashes, close the game and update Plugins/JunBridge.LinuxFix.dll to 0.2, or rerun the bridge installer after updating to a release carrying it. The DLL works with stock MelonLoader 0.7.3 and supplies its helper automatically. If it still crashes, copy the game's MelonLoader/Latest.log before starting it again; crashes before the plugin loads are outside this fix. See Game bridge.
.env is only read on start. Restart her.
Still stuck? Open an issue with the last ~50 lines of the relevant log, your OS and your graphics card. Never paste your .env, your recovery code or your chats.