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:

# Correct
on:
  push:
    tags:
      - v*

Also add workflow_dispatch for manual triggering during testing:

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:

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:

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+):

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):

sudo dnf install -y glib2-devel gtk3-devel webkit2gtk4.1-devel \
  libsoup3-devel openssl-devel librsvg2-dev

Fix (Debian/Ubuntu):

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:

[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:

SELECT name, applied_at FROM _migrations ORDER BY id;

---

Frontend

TypeScript Errors After Pulling

npx tsc --noEmit

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

---

IssueDetail Field Access Errors

get_issue() returns a nested struct:

// 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)