xiaoxia-saas/.learnings/ERRORS.md

Errors

---

2026-06-24 ProjectAssets unsafe return replacement

• Context: Real SaaS UI rollout from V21 prototype.
• Error: Replacing JSX return by broad string/script inserted helper functions inside an effect and broke TypeScript syntax.
• Fix: Reverted ProjectAssets.tsx to stable git version; continue with smaller, scoped edits or separate page files.
• Lesson: For large TSX pages with effects, avoid broad find/replace from first return; use component-scope anchors or rewrite whole file intentionally.

2026-06-24 E2E API unavailable

• Context: V21 UI acceptance run.
• Failure: Playwright core upload/generation/titles failed at auth/register with 500 because Vite proxy could not connect to local API (ECONNREFUSED).
• Fix path: Start local API or point E2E_BASE_URL/API proxy to staging test environment before rerunning core E2E.

ERR-20260624-gitea-runner-fetch-task-404

Logged: 2026-06-24T19:27+08:00 Area: infra/ci

Summary

Gitea Actions runner is running but repeatedly logs ailed to fetch task: unimplemented: 404 Not Found; develop pushes appear in Actions UI but staging repo is not updated.

Impact

CI/CD-first release is blocked until runner/Gitea endpoint compatibility or registration is fixed.

Next Action

Check act_runner config/registration, Gitea actions endpoint compatibility, runner version, and service URL.

[ERR-20260624-STAGING-WEB-BUILD-ON-BUSINESS-SERVER] deploy

Logged: 2026-06-24T22:50:00+08:00 Priority: critical Status: pending Area: infra

Summary

Staging artifact upgrade attempted npm ci && npm run build on the wrong server path and overloaded the machine.

Details

The deploy workflow change 3bffa3c fix(deploy): build staging web artifact added a staging step that ran Node build via Docker on the runner/deploy host. SSH later connected at TCP level but timed out during banner exchange; public HTTPS/health also timed out. The dangerous workflow was reverted by b01ae28 Revert "fix(deploy): build staging web artifact".

Suggested Action

Recover host first, stop residual build/runner tasks, verify production/staging health, then reimplement artifact deploy using isolated builder/CI server and hard resource limits. Add explicit guardrails so business server cannot run npm/pip/docker builds.

Metadata

• Source: error
• Related Files: .gitea/workflows/deploy.yml, docs/V21-UI-ACCEPTANCE-CHECKLIST.md
• Tags: outage, ci-cd, resource-isolation, rollback

---

2026-06-25 - Alembic command must use repo root in API container

• Failed command: docker compose exec api alembic upgrade head from mounted repo path inside staging deploy directory.
• Error: No config file alembic.ini found because the API container workdir is /app/apps/api while alembic.ini is /app/alembic.ini.
• Fix: run docker exec -w /app xiaoxia-api-staging alembic -c alembic.ini upgrade head for lightweight staging migrations.

2026-06-25 - Windows workspace has no local sh/bash

• Failed command: sh -n infra/docker/deploy-production.sh / bash -n infra/docker/deploy-production.sh on Windows host.
• Error: sh/bash command not found in the PowerShell runtime.
• Fix: run POSIX shell syntax checks via an available Linux host/container, e.g. scp to xiaoxia-server and run sh -n on a temporary file.

2026-06-25 - Protected main release must not be direct-merged locally

• Failed action: attempted local develop->main merge and tag push for v0.1.51.
• Errors: main branch is protected from direct push; local main had divergence/conflicts; tag v0.1.51 was pushed from the wrong local main HEAD and then removed.
• Fix: never tag production before protected main has accepted the release commit. Use PR/approved merge path or Gitea API merge, then tag the actual merged main commit.

2026-06-25 - No local Gitea/GitHub CLI in Windows workspace

• Failed command: gh --version / tea --version / gitea --version during release automation.
• Error: commands not found in PowerShell runtime.
• Fix: use Gitea API/server-side tools when available, or the web PR flow for protected-branch releases.

2026-06-25 - Gitea generated token returned API 401

• Failed operation: create release PR via server-side generated Gitea access token.
• Error: API returned 401 on authenticated pull request query/create.
• Fix: verify token output/scopes/API auth behavior before using; do not print secrets, and delete temporary tokens after failed attempts.

2026-06-25 - Business Gitea host lacks runtime-builder SSH key for ref sync

• Failed command: git fetch from git.xiaoxiajianji.com:2222 inside /var/lib/gitea/data/gitea-repositories using /root/.ssh/xiaoxia_runtime_builder.
• Error: identity file missing and Permission denied (publickey).
• Fix: do not install keys ad hoc on the business host; use an already-authenticated local clone bundle or proper Git/Gitea maintenance path to sync refs.

2026-06-25 - Non-ASCII comments in .gitattributes broke Git attribute parsing

• Error: Git printed 'is not a valid attribute name' for Chinese comment text in .gitattributes during merge/fetch operations.
• Fix: keep .gitattributes comments/rules ASCII-only and preserve the LF/CRLF normalization semantics.