# 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.