registrystack / registrystack/registry-stack

CI: Base Registry Engine tutorial job intermittently fails at first-breg fence 03 on an occupied local port

Open
#1,088 0 comments 0 reactions 0 assignees View on GitHub
area:breg bug criticality:p3
Dominant language
Rust
Stars
2
Forks
0
Avg merge
2h 57m
Merged PRs (30d)
128

Description

## What happens

The CI job **Base Registry Engine tutorial from source** sometimes fails in its last step, `Execute the Base Registry Engine tutorial from a reader directory`, when `tutorials/first-breg` fence 03 starts `bregctl dev`:

```text
==> tutorials/first-breg fence 03
bregctl dev refused.

error dev.failed dev
a requested local port is already occupied; stop its owner or choose other
ports: Address already in use (os error 98)
```

A re-run of the same commit passes. Seen three times since 2026-09-01, each time at the same fence (all other failures of this job in that window had other causes):

| Run | Job | Branch | Started |
| --- | --- | --- | --- |
| 34605524639 | 103283307979 | dependabot/github_actions/actions-0b90adc297 | 2026-09-11 |
| 34658987825 | 103457718530 | dependabot/github_actions/actions-0b90adc297 | 2026-09-11 |
| 34960119020 | 104351791845 | fix/casework-unreconciled-binding-reads (#1087) | 2026-09-15 |

## What is known

- The tutorial page starts `bregctl dev` with its defaults: BREG on 8090, the issuer on 8091 and PostgreSQL on 55432 (`crates/registry-bregctl/src/dev/mod.rs`, `StartArgs`). The gate replays the page's fences as written, so it cannot pass other ports.
- Earlier steps in the same job (`dev_lifecycle`, the attachment lifecycle scripts and the retained example recovery test) start complete dev sessions on OS-assigned loopback ports, then stop them.
- The refusal does not name the port, so it is not known which of the three was taken or by what. Naming the port is already tracked in #1076.
- 55432 lies inside Linux's default ephemeral port range (32768 to 60999), so a socket from an earlier step could hold it. That is a hypothesis, not a confirmed cause.

## Proposal

1. Before replaying a page that starts `bregctl dev`, have `docs/site/scripts/check-breg-tutorial.sh` check that 8090, 8091 and 55432 are free on 127.0.0.1. When one is not, print what holds it (for example `ss -ltnp` and `docker ps`) and fail with that port named, so the next occurrence identifies the owner.
2. Once the owner is known, fix the cause in the job (stop or wait for the leftover session, or keep the default ports out of the runner's ephemeral range) rather than retrying the fence.

Until then, re-running the failed job is the workaround.

Contributor guide

Open the contributing guide

Research direction

Start with docs/site/scripts/check-breg-tutorial.sh and the tutorial job that replays tutorials/first-breg; inspect crates/registry-bregctl/src/dev/mod.rs for the default ports in StartArgs. Reproduce or instrument the preflight around 8090, 8091, and 55432 using the diagnostics described in the issue. Done means the failing port and owner are identified and the CI job stops or waits for the leftover session, or otherwise prevents the conflict.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, postgresql, rust, shell
Domain
ci-cd, devops, testing
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.