---
title: Metrix – Common Issues & Resolutions
type: curated
permalink: main/projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/metrix-common-issues-resolutions
stable_id: 1e1b9a7e-5897-4c82-b267-279a8c54b150
scope: project
project_id: d5a7f581-c442-4554-87b9-ee723b8b0258
workspace_type: development
usage_profile_id: null
preference_context: development
document_type: troubleshooting
revision: 1
source_memory_ids: []
source_checkpoint_ids: []
source_file_ids: []
source_git_commit: e660bc7bb4fc5ccda47decb4d514874a148ed9b2
source_git_commits:
- e660bc7bb4fc5ccda47decb4d514874a148ed9b2
source_agent_sync_ids: []
model_connection: Sub2API
model_name: git-restore
source_count: 29
source_revisions: {}
source_dispositions:
  processed: 29
  unchanged: 0
  unsupported: 0
  skipped: 0
cited_source_ids: []
job_cited_source_ids: []
conflicts: []
supersedes: []
preferences: []
source_cursor: 162
source_hash: e2fcea7c8a9e0df7a91925fb2a9beabd922058868310effc908f95df2d78b218
prompt_version: 2026-08-12.3
schema_version: '3'
curation_job_id: null
created_at: '2026-08-19T02:32:30.066112+00:00'
updated_at: '2026-09-23T15:09:30.180462+00:00'
tags:
- troubleshooting
- issues
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

## Troubleshooting Summary (compiled from baseline)

| # | Symptom | Cause | Solution |
|---|---------|-------|----------|
| 1 | Windows directory rename locked (`git status` “cannot move”) | IDE holds handle on `.git` | Stop IDE, move `.git` aside, rename, move back, `git submodule sync` |
| 2 | `/health` endpoint never returns | Async handler performed blocking I/O | Convert handler to regular `def` (thread‑pool) |
| 3 | Docker `exec` sessions disconnect after ~3 s | Default socket timeout | After `exec_start`, call `socket.settimeout(None)` |
| 4 | Missing `api_enabled` flag → `forbidden` error | Flag absent in `core/config.py` | Add `api_enabled: bool = True` (configurable) |
| 5 | Hard‑coded credentials in `pypi_mirror.py` | Placeholder left in code | Use environment variables or Vaultwarden for secrets |
| 6 | `create-module.mjs` typo (`___SNAKE___snapshot`) | Template typo | Fix placeholder to correct name |
| 7 | `pytest.ini` points to empty test dir | No tests present | Add test files or update config |
| 8 | Generic `except Exception: pass` in container exec WS | Swallows errors | Replace with logged exception + WebSocket close |
| 9 | Permission expansion not applied (`resource:* → read`) | Expansion logic missing | Ensure `expand_permissions` runs during seeding |
|10| Shiki theme not syncing on UI theme change | Shiki instance not updated | Watch `appStore.dark`, call `shiki.setTheme` |
|11| Terminal copy‑paste fails on Windows named pipes | Missing error handling | Add UI toast & fallback to TCP |
|12| Column‑width reset on reload | Width stored only in `localStorage` | Persist via `/api/user/preferences` |
|13| Duplicate CGI merge strategy undefined | No config option | Add `duplicate_cgi_merge` setting (`highest|latest|average`) |
|14| Internal PyPI cache grows unbounded | No eviction policy | Background job to delete oldest wheels when limits exceeded |
|15| Re‑reported missing `api_enabled` flag (duplicate) | See #4 | — |

These solutions have been applied where marked **✅ Completed** in the task list. Remaining items are tracked in the **High‑Priority Open Work Items** table (source `curated_baseline:13ffa178‑e9cf‑4735‑8da4‑e1d4cf683a52`).