Skip to main content
Docs

Search documentation

0 articles

    Contents

    Troubleshoot a Termin8 session

    Start with the symptom you can see. Keep existing views open while investigating, preserve unsaved files in the program that owns them, and avoid relaunching a command whose effect is uncertain. A missing terminal view is not proof that its process stopped.

    Typing goes to the wrong place​

    Check: Is the caret in a terminal, a find field, the command palette, a browser address field or a page form?

    • Press Escape to leave terminal find or dismiss a menu.
    • For an embedded web page, use its close control or Command-Escape to return to the terminal.
    • Use Command-B and select the intended open pane, then click its terminal prompt.

    Verify: The intended terminal is visible and has keyboard focus. Only at a shell prompt, use the harmless printf Hello check from the quickstart. Do not send that text to an agent or rerun an earlier command as a focus test.

    Find cannot locate output​

    Check: Command-F searches the focused terminal's retained scrollback, not every session. Confirm the tab and pane, and search for a short distinctive fragment. Capital letters make the query case-sensitive.

    Recover safely: Select the original pane through Open panes and try again. If the output is no longer retained, use an existing log or saved result if the original tool provides one. Do not assume an absent match means the operation failed, and do not repeat a file-changing or external operation just to recreate its output.

    Verify: A matching line appears in the correct terminal, or the tool's own result establishes the outcome separately.

    A shell or agent view is missing​

    Check: Look through existing tabs and Open panes first. A folded or unselected pane is not necessarily a stopped job. If your session menu offers Sessions, inspect All threads or Detached Threads and read the actual status and identity before acting.

    Recover safely: For a listed existing thread, use its Focus / reconnect action rather than starting the task again. Confirm the folder, process and retained output match the work you wanted. Reconnection to an existing thread is not the same as starting a new shell or restoring a terminated program.

    Do not choose End Thread to refresh a view: it stops the selected job. Do not delete local session state or kill helper processes as a first repair. If the session is absent or unavailable, preserve the visible error and stop before creating duplicate work.

    Verify: The intended existing session is visible and its status/output make sense. A title alone is not evidence that a long-running task completed or that a remote operation succeeded.

    Termin8 reports nonpersistent work​

    Check: A notice beginning Nonpersistent means the app could not initialize its persistent workspace. In this mode, threads can end when the app quits. Do not test recovery by quitting valuable work.

    Recover safely: Save files through their owning application and record important results somewhere durable. Keep the app open while you collect the non-secret error. If a message identifies a permissions or free-space problem, investigate that specific cause without clearing settings or session data. Repeated restarts are not a repair for unavailable persistence.

    Verify: A subsequent successful setup and reconnection must be checked with disposable work before relying on it. Neither a saved layout nor an old scrollback line guarantees a live process. Do not expect recovery across every crash, machine restart or ended job.

    A web page is blank or fails to load​

    Check: Read the address and loading/error status. Confirm you intended a public HTTP or HTTPS page. Note whether the view is using private or saved browser storage; a private view is not expected to carry every earlier signed-in state.

    Recover safely: Correct a mistyped address, or try a known public page. Do not repeatedly submit a form or repeat a purchase to test connectivity. If necessary, open the intended public page in your usual browser, without copying credentials or private tokens into a report. Use the browser close control or Command-Escape to leave the page.

    Verify: Actual page content at the intended address, not just a loading indicator. A successful public page load does not test sign-in or every site's compatibility.

    A local preview is refused or looks different​

    Check: Preview file needs an existing supported file, not a folder. Supported groups include common images, Markdown, HTML and text/source documents. The file limit is 16 MiB; PDF, SVG and Office documents are not supported by this preview route. Local HTML preview does not execute scripts.

    Recover safely: Check the file you selected and use an appropriate viewer for unsupported content. Do not rename a file extension to pretend it is supported, overwrite the original, or reduce a valuable document just to pass preview validation.

    Verify: The intended document opens, or its owning application can read the original. A preview is not proof that edits have been saved.

    Keep enough detail for help​

    Record the installed app version, the action you chose, the visible error, and whether the issue affects a shell, agent, embedded page, local preview or background command. Include a minimal reproduction using disposable work. Remove credentials, private URLs and sensitive terminal output before sharing. Background-command output is bounded and available for the current app run, so preserve useful non-secret details before leaving it. See the keyboard reference for action scope.