The Neconyan handbook
Your guides Miso, Taro & Nori
Choose each guide's gender to change their artwork and pronouns. Your choices stay in this browser, separately from the app.
Something went wrong¶
Find the symptom below and start there. Change one relevant thing at a time and keep the original error message.
The page won't open¶
Check that the launcher is still running and hasn't stopped with an error. On the computer running Neconyan, open the address printed in the terminal; the default is:
If another program is using that port, the terminal should report it. Stop the conflicting copy or use a different configured port, then open the matching address.
On a phone, use the computer's network address, not localhost. Check that both devices share a network, the server is listening for network connections and the firewall permits access. Follow the phone guide for authentication and address allow-list settings.
If Neconyan cannot finish loading¶
When startup fails in a way the page can catch, Neconyan shows Neconyan could not finish loading with the recorded error, Retry startup and Read report. Retry startup reloads the page and keeps saved browser data; it doesn't clear the cache or start a reload loop. Read report opens the retained error even though the app didn't finish starting.
If the same error returns, read the report and check the launcher terminal before clearing site data. Clearing browser storage can remove the report and other saved settings. A failure that stops the page before this panel can run still uses the recovery screen or saved crash report described below.
If two starts do not finish¶
When two browser starts in a row don't finish, the next load shows Neconyan could not finish starting instead of the app, with the time of the last recorded activity when one exists. Start Neconyan continues a normal start. Read crash report opens the retained report before any application work begins. Clear frontend cache and reload removes cached frontend files, resets the failed-start count and reloads. Start in low-memory mode saves that choice before starting.
On an iPhone or iPad, a startup crash loop turns low-memory mode on automatically unless you set it off. That setting is saved, so low-memory mode stays on until you change it in Settings. When automatic mode is on, the button reads Start without low-memory mode. Any start that reaches readiness clears the failed-start count. A clean close or a new tab doesn't inherit another tab's crash loop.
If a phone app stops at startup¶
The Android and iPhone apps keep a small ownership record inside their data folder, so two copies can't write to it at once. A run that Android or iOS closed without warning can leave that record behind. Both apps now clear a record left by their own earlier run and log Reclaimed a stale data folder lease in server.log, and both still refuse when the earlier server may be running or when the record holds something the app never writes.
On Android, the recovery screen names the lock fields that differ. Close Neconyan from the recent apps screen or force stop it in Android settings, then press Try again; include the message in a bug report if it comes back. Save a backup from that screen when it says the lock needs checking. On iPhone, Try again and Share startup log stay available, and the shared report ends with the last part of the server log.
Read the reason on the screen before pressing either button. Install on Android and Open it on your phone cover the screens in full.
The page opens but the model won't reply¶
Open Connections and check the provider, model, key and endpoint. A loaded model list doesn't prove the selected model accepts generation requests.
| Error or symptom | Check first |
|---|---|
| Unauthorised, invalid key, 401 | Correct provider, current key and API access |
| Forbidden, 403 | Account permissions, model access or server access rules |
| Rate limited, 429 | Provider limits, available credit and simultaneous helper requests |
| Model not found | Exact model identifier and availability on this endpoint |
| Connection refused or unreachable | Model service running, address and port reachable from the Neconyan server |
| Unsupported parameter or bad request | Requested features and limits supported by that model |
| Context too large | Input size, history, lore, helper context and reserved reply space |
Providers can use error codes differently. The returned message is more useful than the number alone.
A reply is taking a long time¶
Look at whether Neconyan is preparing the request, waiting for the provider, receiving output or waiting for a required helper. Focus on the stage that's taking time. For example, changing the writing prompt won't fix a helper waiting for an unavailable connection.
Check Agent activity, Mewmory jobs and the selected connection. Try a short request with one character and the minimum relevant helpers to isolate the cause. Before retrying, establish what happened to the previous request.
Streaming displays output as it arrives; it doesn't guarantee that the provider begins immediately. Closing the tab also doesn't cancel work already accepted by the server. Use the explicit Stop control when you want cancellation.
If a Guided Generations preview seemed stuck on 'Writing reply…' after you switched tabs, update to 1.3.0. The preview now reconnects when you return and catches up with the server's text.
A server reply says there is no room¶
When a server reply, save or import reports that protected Roleplay evidence has no room, it has reached the fixed 16 MiB protected-record capacity, not a disk-space limit. Your chat isn't necessarily damaged. A reply you stopped releases its reservation once the server records the stop; retry after it settles. A reply that failed or was interrupted keeps its reservation until its job leaves saved history, because it may still be collected or retried. Each admission reserves about 72 KiB (64 KiB plus an 8 KiB receipt) while it can still be saved.
A reply stops with a macro error¶
This message means a prompt built on the server uses a macro that only works in the browser:
The {{name}} macro is browser-only in Macro Enhanced and cannot run in a server prompt. Remove it or use a supported core macro.
Ordinary Roleplay replies build their prompts in the browser and can use it. Conversation replies, Deep Swipe replacements, protected Guided corrections and Roleplay replies with a selected Notebook context build theirs on the server, so the reply stops before anything is sent to the model. That includes an ordinary reply when On the server is selected under Settings → Chat & Writing → Chat & messages → Replies → Where replies are written. Find the named macro in the card, preset, lorebook entry or message and replace it with a core macro, or remove it. See Macro Enhanced in Roleplay prompts for what still works.
The page freezes after a reply in a long chat¶
Before 1.3.0, a long chat with a lot of Agent history could freeze the page for minutes after each reply, long enough for Android to close the app. Update to 1.3.0, then try the chat again. If it still freezes, collect a report as described below.
A chat or note seems missing¶
Confirm the server address and account. An Android installation and a computer installation have separate data unless you've transferred it. In Conversation, also check the persona and branch.
Try Search everything with a distinctive phrase. It searches saved chats, notes, character definitions and lorebook entries in the current account. A warning that some content couldn't be searched means results are incomplete. Unsaved drafts aren't included.
For Roleplay, check the selected character or group and saved chat history. Chat Archive can help find saved files, including orphaned files no longer linked to an existing card. Temporary chats aren't saved.
For notes, check the notebook, Trash, history and save status. Saved on this device only isn't confirmation that another device can retrieve the note from the server.
A chat import is refused¶
For a chat from another installation, read Import as new instance and explicitly select it when you want a separate character instance. A normal import doesn't automatically bypass origin checks. Keep the source files and read the error before retrying.
If a saved ZIP import asks for its archive again after reinstalling, select the original ZIP. The browser may remember an import whose uploaded source is no longer on the server.
Chats stopped opening after copying folders¶
Copying data folders into an installation by hand can break the records Neconyan uses to track saved files, even when the chat text is fine.
- Open Settings → System & Device → Import & Restore → Repair transferred data.
- Press Check transferred data and read the report. Nothing changes yet.
- Press Back up and repair. Neconyan backs up your chats, character cards, groups and tracking records first, then accepts the files on disk.
- Press Reload repaired account before opening or saving chats.
A chat or character card that can't be read, or whose file name ends in a space or a full stop, no longer blocks the whole repair. The report lists it under 'Repair will leave out this file and keep it unchanged on disk:', and everything else is repaired. Rename or fix the file, then check and repair again to include it. A broken group file still blocks the repair, because it affects the whole group list. Leftover import uploads and saved backup downloads are skipped. Any other refusal names the file it couldn't check.
For future transfers, use Import Folder or Import Backup ZIP instead of copying files into a running installation.
Image input needs attention¶
An image input notice means a saved picture can't join new automatic replies yet, usually because its choice needs review or the referenced file changed. Open Settings → Appearance → Avatar & Chat Styles → Review chat images, or click the Review needed before replying notice itself.
A refused reply built in the browser now shows that notice too, and a nested or group call shows one notice rather than several. Each new Send can still show its own notice. Deep Swipe and Guided Correction don't add a second error toast for the same refusal, and Prompt Manager's background prompt count ignores it instead of raising a hidden error. Opening the review doesn't save the current chat first; it opens the chat that was refused.
For Roleplay, the review has three views. Current chat lists every attachment location in the open chat; choose Send the image, Use a description, Show only or Remove from message per image and press Save choice. Choose chats reviews several saved chats, with Stop sending images in selected chats and Save copies of images stored in selected chats for a batch. Each chat is saved separately with its own backup, so a chat that fails doesn't undo the ones that already finished, and copy-only changes keep the existing descriptions and choices.
Change history holds earlier changes: Finish this change completes a prepared change, Discard unfinished change drops one whose preparation did not finish, Download backup exports the chat as it was before that change, Undo change restores it, and Delete backup ends undo availability while keeping image files and compatible copies. Undo is refused once the chat has changed since; download the backup instead. A missing original image can't be reconstructed by undo.
Older saved messages may embed images that need a prompt-sized compatible copy first. Prepare a converted copy prepares one and shows the result before anything changes; choose a local replacement instead of downloading the original from its website, and note that the download asks for confirmation first because the website may refuse browser access. Save a copy as it is saves an embedded image as a compatible copy without converting it, Use the copy already on this server points at a matching account file, and Make this the gallery's chosen image fixes a gallery reference. The displayed picture normally stays as it is; tick Also show this copy in the chat instead of the original in the preview to adopt it, or use Show the compatible copy in the chat once a copy exists. Save choices for selected images applies the ticked rows, and Save copies of selected images stored in the chat prepares copies for several embedded images at once. Opening the review and scanning a chat doesn't contact external image websites.
Limits: a replacement you choose can be up to 16 MiB, and a prepared copy is a still PNG, JPEG or WebP of at most 1 MiB and 2048 pixels per side. Changes apply to at most 128 images at once; review larger chats in smaller groups.
A setting or panel looks broken¶
Try a known bundled theme and disable the specific custom CSS or extension you most recently changed. Reload, then repeat the action that failed. If only one third-party extension triggers the issue, record its version and report it to its author with the Neconyan version.
On a phone, mention the device, browser and whether you're using a Home Screen window or an ordinary tab. Keyboard-open problems need that detail.
A helper works differently from the chat¶
Check the helper's own connection and context preview. Scratchpad, Companions, Mewmory, image generation, speech and translation can each have separate configuration. A successful main reply doesn't establish that those configurations work.
If a lore fact is ignored, inspect World Info Lab or the outgoing prompt. If a memory is ignored, inspect Mewmory's Recall view. Establish what reached the model before changing the writing instructions.
Read saved crash reports¶
If the browser finds an unfinished record from its previous visible page, Read report opens the retained details, even if the server is offline or Debugger is disabled. Background closures stay available for manual reading. An ordinary reload doesn't repeat a notice you've already seen. A missing close record alone doesn't prove a crash.
Open Extensions → Built-in → Debugger → Saved crash reports to read browser reports without turning on live debugging. Each has Copy and Download actions. Administrators can also read retained server reports; other accounts can't. Android crash reports opens the APK's native reader.
I keep these reports on your installation; nothing is uploaded automatically. They record errors and bounded activity measurements, without deliberately collecting chat text, prompts or credentials. An error message or system trace can still contain private text, so read it before sharing. Recent activity shows what was happening, not what caused the failure. Severe memory loss or unavailable storage can prevent a report from being saved. The crash diagnostics reference explains the limits.
Collect a useful report¶
Open Troubleshooting → Debugger in the sidebar, reproduce the issue, then use Diagnostic report in Extensions → Built-in → Debugger to copy or download the report. Read it before sharing. The report omits several sensitive values, but screenshots and surrounding text may still include private information.
Include the app version, device/browser, exact steps, expected result, actual result and error text. Add a screenshot if it explains a layout problem. Remove keys, passwords and private conversation content.
Report reproducible app problems through Neconyan's issue tracker. For a provider account, payment or service outage, the provider's support is the appropriate contact.