Troubleshooting#

Use these checks when evaluating an Automexia development build. Windows, macOS, and Windows-hosted WSL sections describe platform direction, not verified compatibility. Read Development status first.

Start with the smallest reversible check. Do not delete configuration, disable security software, or change shell profiles until the failing component is clear.

For a launch problem, begin with environment checks. For a working terminal that behaves unexpectedly, go to workspace and output. For a settings error, go to configuration reload. Redact private data before reporting an issue.

Check the development environment first#

Record the source revision and operating system.
Compare your toolchain and platform libraries with that revision's README.
Confirm the shell starts normally in another terminal.
Try a non-sensitive directory and default configuration.
Keep the smallest redacted reproduction of the failure.

The website does not offer packages. Do not bypass security software or accept a replacement from an unknown mirror. Read Project trust.

Startup and shell#

Automexia does not open#

Try these checks in order:

Confirm that your system is listed in Platform support.
Confirm the repository's documented development build completed successfully.
Start Automexia once with its default configuration.
Check the desktop session and graphics requirements for your revision.
Keep required runtime resources together as the repository documents.
Follow the repository's support guidance if the failure persists.

Keep another trusted terminal available while diagnosing a development build.

The expected shell does not start#

Automexia uses the configured shell or the operating-system default. Confirm that the shell is installed and can start in another terminal. Then check the shell path and arguments in the configuration reference.

Use a simple shell path before adding profiles or custom arguments. If the default works, restore options one at a time until the failing value is clear.

The working directory is wrong#

Automexia rejects a missing or inaccessible working directory and falls back to a safe location. Check that the path exists, your account can read it, and the path belongs to the intended operating-system environment.

For WSL sessions, a Windows path and a Linux path are not interchangeable. Open the intended WSL distribution first and use its Linux path conventions.

Context appears late or is incomplete#

The shell owns the prompt, history, completion, and command execution. Optional integration adds richer context without replacing those behaviors.

If context is missing:

Confirm the shell is supported by the source revision you are evaluating.
Start a fresh tab with default settings.
Remove duplicate prompt hooks or overlapping shell customizations temporarily.
Run the read-only shell-integration diagnostic documented by the release.
Restore customizations one at a time.

Do not paste unknown prompt scripts into a profile as a shortcut.

Workspace and output#

Tabs, panes, or shortcuts behave differently#

First identify whether focus belongs to a window-level tab, a split pane, or a pane-local tab. Close and navigation actions can use that active scope.

Open the command palette to confirm the current action name and binding. If a custom shortcut conflicts, return that action to its default and test again. See Keyboard and input and Workspaces, tabs, and panes.

Search does not find expected output#

Pane search checks the selected terminal's scrollback. All-pane search checks the active local tab in each visible split; it does not activate hidden tabs or other window tabs.

Confirm the expected output is still in scrollback and that the correct search scope is selected. Long-running sessions may discard old lines according to the configured scrollback limit.

An image preview is empty or unavailable#

Use a supported local image file.
Confirm the file still exists and is readable.
Select or hover the complete path, including spaces.
Use the explicit preview action instead of relying on automatic detection.
In a mouse-reporting terminal application, use the documented modifier so Automexia receives the pointer action.

Remote URLs, pipes, devices, and unsafe path types are rejected. Very large or damaged images may also be refused to protect terminal responsiveness. See Image previews.

The layout looks cramped after resizing#

At very small pane sizes, lower-priority rails and footers can fold away so the terminal keeps usable rows. They return when space is available.

If content stays incorrect after resizing, restore a simpler split layout and open a new tab. Record the window size, display scale, and layout if the problem is reproducible.

Platform and configuration#

WSL commands or file access feel slow#

Linux tools are usually faster when project files live inside the WSL filesystem rather than under /mnt/c or /mnt/d. Windows-native tools work best with files on the Windows filesystem.

Choose the location that matches the tools running in that session. Do not share tool caches between Windows and Linux unless the tool explicitly supports it. This is a project-workflow choice, not an Automexia installation requirement.

Configuration reload fails#

Automexia keeps the last valid configuration when a new file cannot be applied. Read the reported TOML error, correct one value, and reload again. Start from the minimal example in Configuration if the error is not clear.

Keep a backup before a larger configuration change. Avoid downloading complete configuration files from unknown sources because they can change shells, shortcuts, or launched programs.

Logs may contain private information#

Diagnostic logs can include local paths, program names, system details, and process errors. Review and redact them before sharing. Never include passwords, tokens, command history, customer data, private hostnames, or private keys.

Enable logging only for the shortest period needed to reproduce a problem, then turn it off and remove unneeded diagnostic files.

Report a reproducible issue#

Follow the official support guidance. Prepare a redacted report that includes:

Automexia source revision and build environment;
operating system, architecture, and shell;
the smallest safe reproduction;
whether the issue happens with default configuration;
a redacted error or screenshot when it is necessary;
relevant, redacted build or runtime errors.

For a possible vulnerability, contact security@automexia.com. Do not publish exploit details or sensitive terminal data in a general feedback channel.