From 055c52fd708aeb93d67fd1c8c387bd747046068a Mon Sep 17 00:00:00 2001 From: Romuald Lemesle Date: Fri, 27 Feb 2026 14:11:06 +0100 Subject: [PATCH 1/2] docs: add development troubleshooting guide for Yarn/Corepack CI/CD issues Adds a new troubleshooting page under the Development section covering: - Yarn/Corepack HTTP 500 errors from repo.yarnpkg.com - CI/CD build failure workarounds (CircleCI, Drone, GitHub Actions) - Corepack environment variables and fallback strategies - Network and proxy-related build issues Closes #261 --- docs/development/troubleshooting.md | 174 ++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 docs/development/troubleshooting.md diff --git a/docs/development/troubleshooting.md b/docs/development/troubleshooting.md new file mode 100644 index 00000000..8cf26c5b --- /dev/null +++ b/docs/development/troubleshooting.md @@ -0,0 +1,174 @@ +# Development Troubleshooting + +This guide provides solutions to common issues encountered during development, building, and CI/CD pipelines for OpenAEV. + +## Yarn / Corepack issues + +### HTTP 500 error from repo.yarnpkg.com + +**Symptom:** + +Build fails with an error similar to: + +``` +Error: Server answered with HTTP 500 when performing the request to +https://repo.yarnpkg.com/4.11.0/packages/yarnpkg-cli/bin/yarn.js +``` + +This error occurs when the Yarn repository (`repo.yarnpkg.com`) returns a server error (HTTP 500) while Corepack tries to download the Yarn binary. This is typically a **transient upstream issue** — the Yarn package registry is temporarily unavailable. + +**Impact:** + +This affects any CI/CD pipeline (CircleCI, Drone, GitHub Actions, etc.) that uses Corepack to manage Yarn versions, as well as local development setups relying on Corepack. + +**Solutions:** + +#### 1. Retry the build + +Since this is usually a transient server-side issue, simply **re-running the failed CI/CD job** is often sufficient. Most CI platforms support manual or automatic retries: + +- **CircleCI**: Click "Rerun" on the failed workflow. +- **Drone**: Click "Restart" on the failed build. +- **GitHub Actions**: Click "Re-run failed jobs" on the workflow run. + +#### 2. Pin and cache the Yarn binary + +To avoid downloading Yarn from the registry on every build, you can enable Corepack to use a locally cached version: + +```bash +# Download and cache Yarn binary ahead of time +corepack prepare yarn@4.11.0 --activate +``` + +In your CI configuration, cache the Corepack directory to prevent repeated downloads: + +- **Corepack cache location**: `~/.cache/node/corepack` (Linux) or the path defined by `COREPACK_HOME`. + +Example for **GitHub Actions**: +```yaml +- name: Cache Corepack + uses: actions/cache@v4 + with: + path: ~/.cache/node/corepack + key: corepack-yarn-${{ hashFiles('package.json') }} + +- name: Enable Corepack + run: corepack enable + +- name: Install dependencies + run: yarn install +``` + +Example for **CircleCI**: +```yaml +- restore_cache: + keys: + - corepack-yarn-v1-{{ checksum "package.json" }} +- run: + name: Enable Corepack and install + command: | + corepack enable + yarn install +- save_cache: + key: corepack-yarn-v1-{{ checksum "package.json" }} + paths: + - ~/.cache/node/corepack +``` + +#### 3. Use COREPACK_NPM_REGISTRY as a fallback + +If `repo.yarnpkg.com` is persistently unavailable, you can configure Corepack to use an alternative npm registry to download the Yarn package: + +```bash +export COREPACK_NPM_REGISTRY=https://registry.npmjs.org +corepack enable +yarn install +``` + +This tells Corepack to fetch the `yarn` package from the npm registry instead of the default Yarn repository. + +#### 4. Install Yarn without Corepack + +As a last resort, you can bypass Corepack entirely and install Yarn directly: + +```bash +# Using npm +npm install -g yarn@4.11.0 + +# Or download directly +curl -fsSL https://yarnpkg.com/install.sh | bash +``` + +!!! warning "Version consistency" + When bypassing Corepack, ensure the Yarn version you install matches the version specified in your project's `package.json` (`packageManager` field) to avoid inconsistencies. + +### Corepack not found + +**Symptom:** + +``` +corepack: command not found +``` + +**Solution:** + +Corepack is included with Node.js >= 16.10 but may not be enabled by default. Enable it with: + +```bash +corepack enable +``` + +If Corepack is not available, ensure you are using a supported Node.js version (>= 20 recommended for OpenAEV): + +```bash +node --version # Should be >= 20 +``` + +## Network and proxy issues + +### Builds failing behind a corporate proxy + +If your CI/CD environment or development machine is behind a proxy, package downloads may fail. + +**Solution:** + +Configure the proxy for both npm/Yarn and Corepack: + +```bash +# For Yarn +yarn config set httpProxy http://proxy.example.com:8080 +yarn config set httpsProxy http://proxy.example.com:8080 + +# For Corepack / Node.js +export HTTP_PROXY=http://proxy.example.com:8080 +export HTTPS_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +``` + +### SSL certificate errors during package install + +**Symptom:** + +``` +Error: unable to verify the first certificate +``` + +**Solution:** + +If your environment uses a custom CA or self-signed certificate: + +```bash +# Point Node.js to your CA bundle +export NODE_EXTRA_CA_CERTS=/path/to/your/ca-bundle.crt +``` + +!!! warning "Security" + Avoid disabling SSL verification (`NODE_TLS_REJECT_UNAUTHORIZED=0`) in production or CI environments. Always prefer adding the correct CA certificate. + +## Getting help + +If you continue to experience build or development issues: + +1. **Check the logs** for specific error messages. +2. **Search the [Filigran Community on Slack](https://community.filigran.io)** for similar issues. +3. **Open an issue** on the [OpenAEV documentation repository](https://github.com/OpenAEV-Platform/docs/issues) if you believe documentation is missing or incorrect. From 6f4adf308abf19d40f99469fbde62e0e6f44bd2b Mon Sep 17 00:00:00 2001 From: Romuald Lemesle Date: Fri, 27 Feb 2026 14:11:31 +0100 Subject: [PATCH 2/2] docs: add development troubleshooting page to navigation --- mkdocs.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 579624d7..2d417f15 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -216,6 +216,4 @@ nav: - Injectors: development/injectors.md - REST API: development/api-usage.md - Best Practices: development/translations.md - - - + - Troubleshooting: development/troubleshooting.md