Optics Docs
GitHub

Get help

Find the answer to a problem yourself, or report it so someone else can.

View as Markdown

Most problems have a known fix. Start with the pages below, and ask on GitHub when they don't cover your case.

TroubleshootingFixes for common install, setup and run problems, listed by the message you see.FAQShort answers about what Optics does, what it doesn't, and why.GlossaryEvery term the docs use, in one place.

Where to look first#

Run optics doctor on your project before anything else. It checks Python, every engine, the Appium server, connected devices and your config.yaml, and prints the fix next to each problem:

$ optics doctor my-project

Always pass the project folder. Without it, doctor checks your machine but not your config. If doctor shows no ❌ rows and the problem remains:

  1. **Search Troubleshooting for the exact message.** Problems are listed by the words Optics prints, such as No driver enabled or Element not found.
  2. Look up the code. If the message has a code like E0201, Error codes says what it means and what to do.
  3. **Read the FAQ** when something works differently from what you expected. Some behavior is a known limit, not a bug.

Ask a question or report a bug#

Open an issue on GitHub. Search the open and closed issues first, since someone may have hit the same problem.

A good report lets someone reproduce the problem without asking you anything. Include:

  • Your Optics version. Run optics --version.
  • **The optics doctor output for your project.** Run optics doctor <project> and paste everything it prints.
  • **Your config.yaml, without secrets.** Remove API keys, passwords and tokens, and replace private URLs with placeholders.
  • The failing step. Paste the rows from modules/modules.csv and test_data/elements.csv that the step uses, and the full "Failure details" box from the run.
  • The log. Choose the one that matches what you ran:
    • optics execute: set file_log: true in config.yaml, run again, and attach execution_output/internal_logs.log and execution_output/execution_logs.log. Set log_level: DEBUG for the most detail.
    • optics live: attach logs/optics_live_<time>.log from the project folder. Its path is printed when you quit.
  • What you expected, and what happened instead. A screenshot from execution_output/ often shows the difference at a glance.

Report a security issue#

Don't open a public issue for a security problem. Report it privately, as described in the repository's security policy.