Diagnosing Subversion Repository URL Changes: When to Relocate and When to Re-Checkout

The recognizable condition

After a Subversion server move, rename, scheme change, or reverse-proxy path change, commands that worked yesterday start failing with Repository moved permanently, No such revision, Unable to connect to a repository at URL, or Repository UUID mismatch. Notably, svn status may still succeed because it reads local metadata in the .svn directory rather than contacting the server. The immediate engineering decision is whether to repoint the existing working copy with svn relocate or abandon it for a fresh checkout. Choosing wrong can either hide a repository identity change or waste hours re-downloading history.

Cause and diagnostic table

Condition	Likely cause	Diagnostic signal
Same repository, new root URL	Server moved, renamed, or path remapped	svn info shows the old URL, but the Repository UUID matches the target
Different repository	Content replaced or wrong target URL	UUID differs or history has gaps
Redirect or proxy path change	Reverse proxy exposes a temporary or non-canonical path	Repository root returns 301/302 or an inconsistent scheme
Stale client	Working-copy format unsupported or old server	Client version incompatible with server or working copy
Local lock	Previous operation interrupted	svn status reports locked items; cleanup needed before network checks

Ordered checks

1. Check the client version. Run in a terminal:

   svn --version -q

   Expected: a client from the same supported era as the server. Risk: older clients may not support the current working-copy format.

2. Inspect local metadata. Run in the working copy root:

   svn info

   Expected: the old URL and Repository UUID are readable. Risk: none; this is read-only.

3. Query the new repository root. Run in a terminal, substituting your target URL:

   svn info https://svn-new.example.com/repo/project

   Expected: the Repository UUID is identical to step 2, and the Repository Root reflects the new path. Risk: an authentication prompt if credentials changed.

4. Test history continuity. Run in the working copy root:

   svn log -l 5 ^/

   Expected: recent revisions match server expectations. Risk: network timeout if a proxy is misconfigured.

5. Check working-copy locks. Run in the working copy root:

   svn status

   If locks are present, run:

   svn cleanup

   Expected: a clean status before repointing. Risk: cleanup releases stale locks; ensure no other SVN process is running.

6. Only then attempt repoint.

Fixes tied to findings

Matching UUID and clean history

If the UUID matches and history is continuous, repoint the working copy metadata. Run in the working copy root:

svn relocate https://svn-old.example.com/repo/project https://svn-new.example.com/repo/project

Older clients may expose only the deprecated form:

svn switch --relocate https://svn-old.example.com/repo/project https://svn-new.example.com/repo/project

Then run svn update. Do not combine relocation with branch switching in one command; repoint first, verify, then switch.

UUID mismatch or missing history

Do not relocate. A different UUID or history gap means the target is not the same repository. Plan a fresh checkout or a server-side dump/load instead.

Redirect or proxy path change

Fix the server or proxy to expose one canonical repository root. Do not rely on svn relocate to follow redirects.

Stale client

Upgrade the client or use a compatible server bridge.

Local locks

Run svn cleanup, then retry the checks above.

The engineering decision

Treat svn relocate as a metadata-only repoint for identical repository content. Never use it to change repositories, to work around incompatible authentication, or to “fix” checksum errors. Validate on a pilot working copy and keep the old URL available until svn update and svn status are clean.

Escalation criteria

• UUID matches but svn update still fails — escalate to server or release owners.
• Redirects are required — escalate to server or proxy owners.
• The repository root must change without a history rewrite — escalate to release owners.
• Many users need a coordinated cutover — escalate to release owners.
• Any error suggests corruption — stop and escalate immediately.
• The move also changes authentication, TLS, or access paths — escalate to security.

Limitations and verification

A repository root change can break svn:externals, hooks, CI configurations, and absolute URLs. Audit those before cutover. Command availability and deprecation vary by client version; confirm whether your client exposes svn relocate or only svn switch --relocate before scripting it.

Verify the result with these checks:

• Run svn info before and after. The Repository UUID must stay identical while the URL and Repository Root change.
• Run svn status and svn update on a pilot working copy. Expect no tree conflicts or checksum errors.
• Run svn log -l 1 ^/ and compare the newest revision with the server’s expected head.
• If a proxy is involved, request the repository root and confirm it returns the final canonical URL without a redirect.