tool-mapmint/docs/impl/reports/VALHALLA-ARM64.md

Valhalla on the Jetson: arm64 viability and the driving-side trap

Date: 2026-09-04
Host: mikkeli-orin-nano-2 (192.168.2.209), aarch64, Ubuntu 22.04.5, L4T R36.4.7 / JetPack 6
Outcome: arm64 works. A separate, silent correctness bug was found and fixed.

Why this was investigated

Valhalla's arm64 container support was recorded as the one real integration risk in the navigation workstream, on the strength of a long-running upstream issue (valhalla/valhalla#3424) about building arm64 images. Everything else in the workstream was blocked behind the answer.

arm64: not a risk

The issue is stale. Checked before pulling anything:

docker manifest inspect ghcr.io/valhalla/valhalla:latest
  → linux/amd64, linux/arm64

Both ghcr.io/gis-ops/docker-valhalla and ghcr.io/nilsnolde/docker-valhalla also publish arm64. The official image runs natively; valhalla_build_config, valhalla_build_admins and valhalla_build_tiles all execute. Version 3.8.3.

Full pipeline verified: config → timezones → admins → tiles → served route.

Measurement	Value
Shikoku PBF	49 MB
Routing tiles from it	149 MB
Whole-Japan PBF	2.4 GB
Admin DB from whole Japan	17 MB
Timezone DB	116 MB
Route Takamatsu → Matsuyama	157 km, 112 min

Japanese street names survive intact in the route narrative (高松南バイパス, 高松停車場栗林公園線/173), so CJK is fine on the routing path as well as the rendering path.

A benign warning appears at startup:

[ERROR] (stat): /data/valhalla/tiles.tar No such file or directory
[WARN] Tile extract could not be loaded

The server falls back to the tile directory, which is the form we want anyway. Not an error condition. Do not "fix" it by switching to the tar.

The actual finding: a sub-region extract silently mirrors the map

The plan said to start from a regional extract to keep artifacts small. That is correct for routing tiles and wrong for the admin database.

Built from shikoku-latest.osm.pbf:

by admin_level: [(4, 4)]
  (4, '36', '徳島県', drive_on_right=1)
  (4, '39', '高知県', drive_on_right=1)
  (4, '38', '愛媛県', drive_on_right=1)
  (4, '37', '香川県', drive_on_right=1)

No admin_level=2 row at all, and right-hand traffic on every prefecture.

Built from japan-latest.osm.pbf:

by admin_level: [(2, 1), (4, 47)]
  (2, 'JP', '日本', 'Japan', drive_on_right=0)

Driving side is a country-level property. A Shikoku-clipped extract does not contain Japan's country boundary, so no country record exists and the value defaults to 1.

Why this is dangerous

valhalla_build_admins exits successfully. Nothing warns. Nothing fails. The tiles build fine and the server serves routes. The first symptom is a turn instruction that is subtly wrong, on a road the driver may not know well.

The fix

The admin build and the tile build are separate invocations reading the same config, so they can take different inputs:

• admins ← japan-latest.osm.pbf (always the full country)
• tiles ← whatever regional extract is wanted

Cost is one 2.4 GB download, which is not repeated per region.

The rule that follows

Never assume this worked. Every build asserts that a country-level row exists and reports drive_on_right=0 before its tiles are treated as usable. A check is cheap; the failure is silent and the consequence is on a road.

Left on the host

~/valhalla-test/ — 2.8 GB, kept deliberately. It is a working Valhalla install with the Japan PBF already fetched, which is the expensive part to reproduce.