Troubleshooting

1. Check you're on the right site: ourchirp.com for hosted sites, or your own server's address.
2. Passwords are case-sensitive; check Caps Lock and autocorrect. Forgot it? Contact us (hosted sites) or ask whoever runs your server.
3. New to a site? You need an invite code from whoever runs it. Tap Create account and enter it.
4. On the iPhone app, close it fully (swipe it away) and open it again.

One password works for every site you belong to; changing it on one changes it everywhere.

Your browser or the app kept an older copy. Reload the page; on a computer use Shift-reload (⌘⇧R or Ctrl⇧R). On iPhone, close Chirp and open it again.

Check the version at the bottom of the menu, or in ⋮ → Changelog, against the newest release listed there.

• Check the phone has internet: open any website in Safari.
• If other sites work, the Chirp server may be restarting after an update. Wait a minute and pull down to reload.
• Running your own server? Make sure it's on and reachable from outside your home (see reaching your server away from home).

The map tiles come from CARTO, which now needs a key. On ourchirp.com this is set up. On your own server, get a free key at carto.com/basemaps/apikey ↗ and set CHIRP_CARTO_KEY (Unraid: CARTO map key). Restart the container.

Restrict the key to your site's address in the CARTO dashboard: it travels with every map tile, so anyone viewing a map can see it.

Upload it again from ⋮ → My Profile (tap the camera on your picture). Photos uploaded before version 0.5.14.s were saved but never displayed. JPEG, PNG, HEIC, WebP and GIF all work.

That's on purpose: opening Recordings from the tab bar or menu starts fresh. Use Back (the ‹ arrow at the top, your browser's back button or a swipe back) to return to the same page, filters and scroll position.

Turn the phone to portrait and back, then reload. If it stays, take a screenshot and send it to us with the page name. These are quick to fix.

1. iPhone Settings → Chirp → Notifications: allow them.
2. In Chirp, ⋮ → Settings → My Notifications: turn on the alerts you want (new species, Daily Journal, digest, watched birds).
3. Send yourself a test from the same page.
4. Focus modes and Notification Summary can hold alerts back; add Chirp as an allowed app.
5. On your own server, an admin needs a push relay token or Apple key in Settings → Alerts & Email.

Everything sent also stays in the Notifications tab, so you can check whether the alert was created at all.

Usually two Chirp servers both know your phone: an old server you used before and the one you use now. Each sends its own copy, and the wording often differs (two Daily Journals, for example).

• In the iPhone app, switching servers with Change server now takes your phone off the old one.
• On an old server you keep running, set CHIRP_NOTIFICATIONS_OFF=1 to stop its pushes and emails.

Apple delays pushes in Low Power Mode and when the phone is idle for a while. New-species alerts go out once the station uploads and the server finishes identifying the recording, usually within a minute. The Daily Journal is sent at 6 pm and the digest at the time your site sets.

• Check spam, and add the sender to your contacts.
• Own server: set up the email server in Settings → Alerts & Email → Email (SMTP) and press Test configuration. Gmail needs an app password, not your normal one.
• If the server has CHIRP_NOTIFICATIONS_OFF=1, it sends no email at all.

Admins choose these in My Notifications. A station counts as offline after it misses its check-ins for the delay set in Settings → Alerts & Email; raise the delay if Wi-Fi blips set it off.

1. Open Chirp on the paired iPhone and sign in. The watch signs in by itself within a few seconds.
2. Keep Chirp open on the iPhone and tap Try again on the watch.
3. Still stuck: restart the watch, then repeat.

The watch's sign-in lasts 30 days and renews whenever the iPhone app is open.

• "Needs an update": the server is older than 0.5.15. Hosted sites already have it; on your own server, update the container.
• Recordings don't play while Live Detect is listening. Stop listening first.
• No sound: turn up the volume with the Digital Crown while it plays, and check the watch isn't in Silent Mode with headphones expected.
• It plays the first minute of each recording, downloaded over the watch's Wi-Fi, cellular or the iPhone, so the first play takes a few seconds.

• Allow the microphone: on the watch, Settings → Privacy & Security → Microphone → Chirp.
• Hold your wrist up and away from your sleeve; wind and clothing rubbing drown out birds.
• The status line shows how many clips were checked. If it stays at 0, the watch can't reach the server: check Wi-Fi or that the iPhone is nearby.

1. Is it powered? A Raspberry Pi 5 needs the 27 W (5 V, 5 A) supply; weaker ones cause random restarts.
2. Is it on Wi-Fi? ping its address from a computer on the same network.
3. Read its log: journalctl -u chirp-device -n 50 on the Pi.
4. Check upload.server_url in config.yaml is your current server, e.g. https://www.ourchirp.com/api/v1/recordings/upload, and that the api_key matches a key in Devices.
5. Restart it: sudo systemctl restart chirp-device.

A station still pointing at an address you've retired keeps uploading into nothing. After moving servers, update every target in config.yaml.

• Run python main.py --test-audio on the Pi and whistle. If the level doesn't move, the microphone isn't being heard (see microphone not found).
• python main.py --test-upload checks it can reach the server.
• Quiet day? Recordings without a detection above your site's minimum confidence are hidden; turn on the Unknown only filter in Recordings to see them.
• Check the station's clock is right (date). A wrong clock puts recordings at the wrong time.

⋮ → Changelog → Device lists each station's version and whether a newer one is out. To update, run the station's update steps from the setup guide, then restart it.

• Use ./install-coral.sh rather than the plain installer.
• M.2 Coral on a Pi 5: run ./fix-gasket.sh once, then reboot.
• Devices shows the backend each station uses. CPU-only detection still works, just slower.

The SD card is wearing out or full. Check space with df -h. Turn on deleting recordings after upload in config.yaml, use a high-endurance card, or boot from an SSD.

That's mains hum: 60 Hz in North America (50 Hz elsewhere) and its harmonics, picked up from power wiring or a ground loop. On the spectrogram it's a set of steady lines at the very bottom.

1. The station's hum filter removes it: audio.hum_filter: "auto" in config.yaml (the default since station 1.4.2). Set "60" or "50" to force it on.
2. Move the microphone cable away from power bricks and extension cords, and plug the Pi's supply into a different outlet.
3. Avoid USB ground-loop isolators with plug-in-power microphones (such as Clippy mics): they can cut the mic's power and make the hum worse.

The filter only notches narrow bands at the hum's pitches, so owl hoots between them are kept.

• List what the Pi sees: python main.py --list-devices.
• Unplug and replug the USB mic, or try another USB port (the blue USB 3 ports on a Pi 5 work best).
• If your mic is listed under a name the station doesn't pick, add part of that name to audio.device_name_hints.

• Add a foam or fur windscreen, and shelter the mic under an eave.
• Use Enhance on a recording, or Rumble removed for low traffic noise, to hear the bird better.
• Point the mic away from the road.

Update the station to 1.4.1 or later, which fixed a gap when several mics were merged. If it continues, the Pi may be overloaded or underpowered: check vcgencmd get_throttled (anything other than 0x0 means power or heat trouble).

• iPhone: Settings → Chirp → Microphone on.
• Browser: allow the microphone for the site, and use an https:// address; browsers block the mic on plain http://.

Set your site's location in Settings → General. BirdNET then weighs species by what's expected at your place and season; stations pick up the change within a minute.

The station makes a first guess, then the server checks the recording again with BirdNET v3. When the server's pass doesn't confirm a station detection, it's removed (the Auto-delete device identifications setting in Settings → Detection). Turn that off to keep station guesses alongside the server's.

There are two minimums: BirdNET v3's own minimum (in Settings → Detection, under the v3 choice) and the display minimum for what the app shows. Raise the display minimum to hide low ones everywhere. Since 0.5.14.f, station detections below the v3 minimum are removed when v3 doesn't confirm them.

• Night noise (crickets, distant traffic, dogs) can look like hoots. Open the recording and use AI Second Opinion, which checks the sound against each bird.
• The Low pitch view stretches low notes so you can see the hoot's shape yourself.
• Fix the hum first (above); mains hum sits right where owls call.

• Raise Sensitivity for the station in Devices (default 1.5) to catch faint, distant calls; expect a few more false ones.
• Move the mic closer to feeders or trees, away from walls that echo.
• Check the station is set to your location (above); a wrong location can rule a species out.

• An admin has to turn it on and add an AI key in Settings → AI Features.
• It takes 10–60 seconds; the button shows it's working.
• Not rated means the AI didn't write about that bird. Run it again; recordings checked before 0.5.14.n rate birds from their likelihood instead.
• If your AI provider is out of credit or the key changed, it fails with the provider's message.

Tap Low pitch above the spectrogram. Recordings with an owl or other low caller open that way already; the button switches any recording.

Turn on night flight calls in Settings → Experimental, and make sure the station's night audio is on (station 1.4.0 or later). Calls show up under Night Calls the next morning.

Bat detection needs an ultrasonic microphone (such as an AudioMoth) and Settings → Bats turned on. Bat calls are too high to hear; use Enhanced playback, which slows them into human hearing.

• Read the log: docker logs chirp --tail 100 (Unraid: the container's log icon).
• Set CHIRP_SECRET_KEY to a long random string (openssl rand -hex 32) and keep it the same across updates; changing it signs everyone out.
• Port taken: the web app uses 8768 on the host network. Change CHIRP_PORT if something else uses it.
• The data folder must be writable and have free space.

The joshsalvi/chirp image is built for x86-64 (Intel and AMD), which covers Unraid and most servers. ARM support is planned; for now, build the image yourself from the source on that machine.

• Simplest: put the server behind HTTPS with a reverse proxy or Cloudflare Tunnel, and use that address everywhere.
• For stations only: use Tailscale or the Chirp Headscale container, and set CHIRP_TAILSCALE_ENABLED=true.
• Headscale can't sit behind Cloudflare's proxy: set its DNS record to DNS only and give it HTTPS with the Chirp Caddy container.

The Unraid mover broke a socket file by moving it to the array. Put Headscale's data and run folders (and Chirp's data if it uses Tailscale) on a cache-only share, then restart both containers.

Your server needs permission to send pushes to the Chirp app. Request a relay token from the About page, then paste it into Settings → Alerts & Email → Relay token and send a test from My Notifications.

Keep the old server running with CHIRP_REDIRECT_HOSTS=old.example.com and CHIRP_REDIRECT_TO=https://new.example.com: pages forward to the same path on the new address. Add CHIRP_NOTIFICATIONS_OFF=1 so it stops sending duplicate notifications, and point every station at the new address.

• Settings → Storage & Backup: set Compression quality (lossless FLAC keeps full quality at about half the size) and turn on Auto-delete station recordings that show nothing.
• Archive old recordings: the spectrogram and detections stay, the audio goes.
• Spectrogram images are rebuilt on demand, so clearing their cache is safe.

Use Settings → Storage & Backup for a database backup, and copy the whole data folder (/app/data) for recordings and photos. On the new machine, start the container with the same CHIRP_SECRET_KEY and the copied folder.

The server downloads the v3 model on first start. Check it has internet and space, then restart; the log says when the download finishes. Until then, detection uses BirdNET 2.4.

A Pi slows itself down above about 80 °C and can crash in heat. Give it a fan or a shaded, ventilated box. In freezing weather, condensation is the bigger risk: keep it in a sealed box with a desiccant pack and the mic pointing down.

Stations restart on their own and upload what they saved. Sudden power loss can corrupt an SD card; a small UPS or an SSD instead of the card protects against it.

Squirrels chew cables and foam windscreens; run cable through conduit. Mount the mic where sprinklers don't reach and rain doesn't drip onto it; constant drips read as clicks.

Keys expire, run out of credit or get revoked. AI features then fail with the provider's message, the Field Guide goes empty, or maps show a watermark. Replace the key in Settings (or the container's settings for CHIRP_CARTO_KEY) and try again.

The HTTPS certificate expired. Most proxies renew automatically; check yours can still reach the internet and that the domain's DNS still points to it. The iPhone app and Live Detect need a valid certificate.

Set your site's time zone in Settings → General, and the container's TZ on your own server. On a station, timedatectl should say the clock is synchronized.

TestFlight builds expire after 90 days. Open TestFlight and install the newest build.