Skip to content

Troubleshooting

Jump to bottom
Joe Xu edited this page May 29, 2026 · 1 revision

Troubleshooting

This page covers common setup and runtime problems in the current project.

Windows Virtual Environment Activation Fails

PowerShell activation blocked

Try:

py -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

Use cmd activation instead

py -m venv .venv
.venv\Scripts\activate.bat

Skip activation and use the venv Python directly

.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -e .

python -m uacragent Does Not Resolve

Make sure you installed the package in editable mode:

pip install -e .

This repository uses a src/ layout, so the editable install is the normal setup path.

Missing API Key Errors

Check:

  • your .env file exists
  • the key name matches the provider you selected
  • the app is reading the .env file from the location used by that interface

Current .env lookup:

  • desktop GUI and CLI: <app_data_dir>/.env first, then current working directory .env
  • API server: current working directory .env

Local Embedding Model Does Not Download

First-run local embeddings download their model backend the first time they are used.

Check:

  • internet access
  • write access to the app data directory
  • that the selected local embedding mode is supported in your runtime

Current runtime split:

  • source installs use sentence-transformers
  • frozen builds use the ONNX local path

Current standalone-build limitation:

  • only all-MiniLM-L6-v2 is supported for free local embeddings in the frozen build

Built App Says Local Embedding Is Not Available

In the current standalone app build:

  • only all-MiniLM-L6-v2 is supported for free local embeddings

If you select a different local model in a frozen build, switch back to:

  • all-MiniLM-L6-v2

or use:

  • Gemini embeddings
  • OpenAI embeddings

Desktop Session Reopened but Did Not Re-Index

This may be expected.

When reopening a session:

  • if the saved Chroma index still matches the saved file set, the app reuses the existing retriever
  • if files changed, or if you click Apply, the app performs a full re-index

Generated Outputs Are Missing

Check the workspace output folder:

  • <workspace>/.uacragent/outputs/

If you are unsure where the workspace is:

  • desktop auto session: <app_data_dir>/sessions/<workspace_id>/
  • CLI: <app_data_dir>/cli_run/<workspace_id>/
  • API: <app_data_dir>/api_run/<workspace_id>/

API Rejects My File Paths

Check that every file path in classified_files:

  • is absolute
  • points to an existing regular file
  • resolves under UACRAGENT_ALLOWED_BASE_DIR if that variable is set

API Returns a Weird markdown_path

This is expected in the current local-only design.

markdown_path is:

  • the absolute local path to the generated Markdown file on the machine running the API server

It is not a download URL.

I Changed the App Data Folder and My Sessions Disappeared

This is usually expected when switching to a different app data folder.

Changing the app data folder does not automatically migrate old sessions.

If you want to see the old sessions again:

  • switch back to the old app data folder

If you want to fully relocate them:

  • manually copy the old app data folder contents first
  • then point the app at the new location

Logs

Logs are stored at:

  • <app_data_dir>/logs/uacragent.log

If you need more detail, set:

UACRAGENT_LOG_LEVEL=DEBUG

before launch.

Even in debug mode, very noisy third-party libraries are intentionally clamped so logs stay readable.

Drag and Drop Does Not Work

The desktop app can run without drag-and-drop support.

If drag-and-drop is unavailable, it usually means the optional tkinterdnd2 support is not active in the current environment.

The rest of the app should still work normally.

PDF Export Has Font or Unicode Problems

PDF export depends on available fonts.

If Unicode text renders poorly, install suitable fonts and try again.

The code already attempts OS-specific font fallbacks, but coverage can still vary by system.

Where to Look Next

UACRAgent Wiki

Start Here

Usage

Reference

Clone this wiki locally