tftsr-devops_investigation/docs/wiki/Troubleshooting.md

# Troubleshooting

## CI/CD — GitHub Actions

### Build Not Triggering After Push

**Check:**
1. Verify the workflow file exists in `.github/workflows/` on the pushed branch
2. Check the Actions tab at `https://github.com/msicie/apollo_nxt-trcaa/actions`
3. Confirm the workflow trigger matches the branch (e.g., `push: branches: [main, 'bug/**']`)

---

### Jobs Stuck in Queue

**Cause:** GitHub Enterprise organizations may restrict which repositories can use
GitHub-hosted runners via runner group policies.

**Fix:** Contact your org admin to add the repository to the allowed runner group, or
temporarily make the repo public for a one-time bootstrap run (e.g., to build the
initial ghcr.io images).

---

### `manifest unknown` — Image Pull Fails

**Cause:** The pre-baked CI image (`ghcr.io/msicie/trcaa-linux-amd64:rust1.88-node22`)
doesn't exist yet. This happens before the first `build-images.yml` run.

**Fix:**
1. Go to Actions → Build CI Docker Images → Run workflow
2. Wait for all 3 image builds to complete
3. Confirm images appear at `https://github.com/orgs/msicie/packages`
4. Re-run the failing workflow

---

### Job Skipped on Tag Push

**Cause:** Pattern matching issue with `on: push: tags:`. Use unquoted glob in the workflow:

```yaml
# Correct
on:
  push:
    tags:
      - v*
```

Also add `workflow_dispatch` for manual triggering during testing:
```yaml
on:
  push:
    tags:
      - v*
  workflow_dispatch:
    inputs:
      tag:
        description: 'Release tag'
        required: true
```

---

### Release Artifacts Not Uploaded

**Cause:** `GITHUB_TOKEN` permissions insufficient. The `release.yml` workflow requires
`contents: write` to create releases and upload assets.

Verify the permissions block:
```yaml
permissions:
  contents: write
  packages: write
```

---

## Rust Compilation

### `MutexGuard` Not `Send` Across Await

```
error[E0277]: `MutexGuard<'_, Connection>` cannot be sent between threads safely
```

**Fix:** Release the mutex lock before any `.await` point:
```rust
let result = {
    let db = state.db.lock().map_err(|e| e.to_string())?;
    db.query_row(...)?
};  // lock dropped here
async_fn().await?;
```

---

### Clippy Lints Fail in CI

Common lint fixes required by `-D warnings` (Rust 1.88+):

```rust
format!("{}", x)  →  format!("{x}")
x >= a && x < b  →  (a..b).contains(&x)
s.push_str("a")  →  s.push('a')
```

Run locally: `cargo clippy --manifest-path src-tauri/Cargo.toml -- -D warnings`

Auto-fix: `cargo clippy --manifest-path src-tauri/Cargo.toml --fix --allow-dirty -- -D warnings`

---

### `cargo tauri dev` Fails — Missing System Libraries

**Fix (Fedora/RHEL):**
```bash
sudo dnf install -y glib2-devel gtk3-devel webkit2gtk4.1-devel \
  libsoup3-devel openssl-devel librsvg2-dev
```

**Fix (Debian/Ubuntu):**
```bash
sudo apt-get install -y libwebkit2gtk-4.1-dev libssl-dev libgtk-3-dev \
  libayatana-appindicator3-dev librsvg2-dev patchelf pkg-config
```

---

### Windows Cross-Compile: DLL Export Ordinal Too Large
`/usr/bin/x86_64-w64-mingw32-ld: error: export ordinal too large: 106290`

Fix: `src-tauri/.cargo/config.toml`:
```toml
[target.x86_64-pc-windows-gnu]
rustflags = ["-C", "link-arg=-Wl,--exclude-all-symbols"]
```

---

## Database

### DB Won't Open in Production

**Symptom:** App fails to start with SQLCipher error.

1. `TFTSR_DB_KEY` env var is set
2. Key matches what was used when DB was created
3. File isn't corrupted: `file tftsr.db` should say `SQLite 3.x database`

---

### Migration Fails to Run

Check which migrations have been applied:
```sql
SELECT name, applied_at FROM _migrations ORDER BY id;
```

---

## Frontend

### TypeScript Errors After Pulling

```bash
npx tsc --noEmit
```

Ensure `tauriCommands.ts` matches Rust command signatures exactly (especially `IssueDetail` nesting).

---

### `IssueDetail` Field Access Errors

`get_issue()` returns a **nested** struct:
```typescript
// Correct
const title = detail.issue.title;

// Wrong — field doesn't exist at top level
const title = detail.title;
```

---

### Vitest Tests Fail

Common causes:
- Mocked `invoke()` return type doesn't match updated command signature
- `sessionStore` state not reset between tests (call `store.reset()` in `beforeEach`)