Troubleshooting

CLI

Not logged in. Run buildtree login.

Run buildtree login. In CI, set BUILDTREE_TOKEN to an API token generated from the dashboard.

EACCES: permission denied during npm install -g

Use a Node version manager (nvm, volta, fnm), or configure npm with a user-owned prefix:

npm config set prefix ~/.npm-global

Upload hangs at "Confirming upload..."

Verify BUILDTREE_API_URL points to a reachable host and that egress to the API and R2 is permitted.

"File size exceeds tier limit"

Delete old builds from the dashboard or upgrade the plan. Storage caps: Free 5 GB, Solo 25 GB, Team 100 GB, Business 500 GB.

Upload picks the wrong file

buildtree upload accepts a glob in the artifact config. When multiple files match, the most recent wins. Clean stale artifacts or pin a specific filename in the config.

Install URLs

404 on an install URL

• The build was deleted, either by retention sweep or manually from the dashboard.
• The URL is malformed.
• The project slug is incorrect.

iOS install URL works on desktop but fails on iPhone

iOS requires HTTPS for OTA install. Localhost or plain HTTP will be refused. Use a tunneling tool such as ngrok, or deploy to an HTTPS endpoint.

"Unable to download app at this time" on iOS

The tester's UDID is most likely not in the provisioning profile the .ipa was signed with. See iOS troubleshooting.

iOS install loads but app crashes on launch

• Code signing mismatch. The .ipa was signed with the wrong export method. Rebuild with --export-method ad-hoc.
• Untrusted Developer. Open Settings → General → VPN & Device Management and trust the developer team. If the trust option is missing, toggle Airplane Mode to refresh.

Devices and UDIDs

Registration page shows "Open in Safari"

iOS exposes the UDID to Safari only. Reopen the URL in Safari.

Profile installed but no UDID in the dashboard

Open Settings → Profile Downloaded on the device and tap Install. iOS does not always pop the install sheet automatically.

"Too many pending registrations"

The per-project pending cap is 50. Approve or reject existing registrations, or rotate the registration token from the dashboard.

Dashboard

A new upload does not appear in search

Refresh the page.

Project page is slow with many builds

Known issue at 1000+ builds. Pagination is on the roadmap. As a workaround, delete builds that are no longer needed.

Auth

Magic link email did not arrive

Check spam. Confirm the email address. Magic links expire in 5 minutes; request a fresh one if needed.

"Invalid or expired magic link"

Magic links are single-use and expire in 5 minutes. Request a new one from the login page.

Billing

"Project limit reached" with only one project

Free tier caps at 1 project. Delete the existing project or upgrade the plan.

Builds keep getting deleted on the Free tier

The Free tier has a 30-day retention window. Solo extends this to 90 days. Team and Business have no retention limit.

Still stuck?

Email hello@buildtree.sh with:

• What you tried.
• The exact error message.
• The install URL, if applicable.
• The project slug.