Troubleshooting#

Use these checks with official Automexia Linux Public Alpha packages. Windows, macOS, and Windows-hosted WSL sections concern planned support, not current executables. Read the Alpha limitations first.

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

The package is blocked or unrecognized#

1. Confirm the download started from https://www.automexia.com.
2. Check that the version, operating system, and architecture match your choice.
3. Compare its SHA-256 value with the official checksum file.
4. Verify the Minisign signature on the checksum file using the pinned release key.
5. Stop if the publisher or checksum is wrong.

Do not bypass SmartScreen or Gatekeeper, add an antivirus exclusion, or accept an unsigned replacement. Follow Release trust for the official verification path.

Automexia does not open#

Try these checks in order:

1. Confirm that your system is listed in Platform support.
2. Restart the computer if the installer requested it.
3. Start Automexia once with its default configuration.
4. Check whether another security tool quarantined part of the package.
5. Confirm that required package files were not moved or removed.
6. Use the release's repair or reinstall path if one is documented.

Keep another trusted terminal available while diagnosing an Early Access 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:

1. Confirm the shell is supported by the current release.
2. Start a fresh tab with default settings.
3. Remove duplicate prompt hooks or overlapping shell customizations temporarily.
4. Run the read-only shell-integration diagnostic documented by the release.
5. Restore customizations one at a time.

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

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#

1. Use a supported local image file.
2. Confirm the file still exists and is readable.
3. Select or hover the complete path, including spaces.
4. Use the explicit preview action instead of relying on automatic detection.
5. 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.

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#

General support intake is not open yet. Prepare a private, redacted report for the support channel announced with a release. Include:

• Automexia version and package type;
• 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;
• checksum and signature results for package-trust problems.

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