Practical fixes for the most common problems customers hit during integration and production use.
Authentication issues
Token expired or invalid
Leaf tokens expire after 30 days. If you get a 401 Unauthorized response, generate a new token. Your application should handle token refresh automatically rather than relying on a hardcoded token.
Wrong API owner
If you can’t find Leaf users, fields, or files you expect to see, confirm you’re authenticating with the correct API owner email. Test and production environments should use separate API owners (e.g., leaf-test@yourcompany.com and leaf-prod@yourcompany.com). There is no shared sandbox — you manage environment separation yourself.
Provider connection issues
Provider credentials not working
Every provider requires its own license agreement and potentially detailed commercial agreements before you can pull data through Leaf. Leaf cannot grant you access to a provider’s API — you must finalize those steps with each provider directly.
Common causes of credential failures:
- The OAuth token expired or was revoked by the grower. Check the credentials events endpoint for the specific provider to see the error.
- The provider application hasn’t been approved yet (John Deere requires app verification through their marketplace).
- The grower hasn’t granted the required scopes/permissions in the provider’s consent flow.
John Deere connections
John Deere is the most common source of connection issues:
- You need a separate agreement with John Deere before connecting. Contact your Leaf CSM if you’re unsure about requirements.
- Use the John Deere credentials events endpoint to check for specific error messages.
- If you need to limit data by organization, use
organizationDataSync to scope which John Deere organizations Leaf pulls from.
Climate FieldView connections
- Climate FieldView credentials use OAuth2. If the grower’s token is revoked, you need to re-run the consent flow.
- Check the Climate FieldView credentials events endpoint for connection status.
CNHi connections
- Similar to other providers, CNHi requires its own access agreement.
- Use the CNHi credentials events endpoint to inspect connection errors.
For any provider, the credentials events endpoint is the first place to look when a connection fails. It gives you the specific error and timestamp.
File processing issues
Machine files stuck in “processing”
Files normally process within minutes. If a file stays in processing for an extended period:
- Check the file status endpoint — it shows the processing state for each pipeline step (standardGeojson, cleanupGeojson, summary, units, etc.).
- Look for a specific step that shows
failed with an error message.
- If the file format is unsupported or corrupt, processing fails. Check the
originalFile step status.
File processing failed
The file status endpoint returns per-step status. Common failure causes:
- Unsupported file format or corrupt data.
- Crop type not recognized — if the crop from your machine file doesn’t appear in the crops table, contact support@withleaf.io.
- The file contained no valid GPS data points.
When to upload manually vs. use provider sync
Use provider sync for ongoing data ingestion where a Leaf user has valid credentials. Use manual upload for historical data (e.g., from a USB drive), unsupported providers, or older offline file formats. Both methods produce the same standard GeoJSON output.
Data not appearing
No field operations generated
Field operations require field boundaries. Without a boundary, Leaf still converts machine files and produces file summaries, but cannot create field operations.
Check:
- Does the Leaf user have fields with active boundaries?
- Do the machine files’ GPS coordinates fall within those boundaries?
- Has enough time passed for processing to complete? Use the file status endpoint to verify.
Duplicate billing from duplicate connections
If the same data is processed under different Leaf users, each user’s acreage counts toward your total usage. This happens when:
- The same grower’s credentials are attached to multiple Leaf users.
- The same boundary is connected under multiple Leaf users.
Prevent this by assigning one Leaf user per actual customer and using test accounts during development.
Too much data syncing
Use customDataSync to preview and selectively process certain fields instead of syncing everything from a provider. This controls costs and avoids pulling unneeded data.
For John Deere specifically, organizationDataSync limits which organizations Leaf pulls from.
Webhook (alerts) issues
Not receiving webhooks
- Confirm your alert URL is registered and active — list your alerts to verify.
- Your endpoint must return a
2xx response. If it returns an error, Leaf retries with backoff but eventually stops.
- Check that your server is publicly accessible. Leaf cannot reach
localhost or private networks.
- Verify there’s no firewall or WAF blocking Leaf’s requests.
Webhook payloads not matching expectations
Alert payloads contain event metadata, not the full resource. Use the IDs in the payload to fetch the complete data from the relevant endpoint (e.g., get file, get operation).
Billing questions
How billing works
Leaf charges based on spatially unique acres processed per Leaf user. The charge is triggered when data is pulled and processed by Leaf, not when you query or download the processed data. Re-downloading the same data does not incur additional charges.
Re-processing identical data under new Leaf users counts multiple times. Be careful when re-creating Leaf users or moving credentials between users.
Checking usage
Use the billing contracts endpoints to view your current contracts and consumption. The consumption range endpoint shows daily usage breakdowns.
Getting help
If your issue isn’t covered here:
- Email support: help@withleaf.io
- Contact your Leaf CSM for billing or commercial questions
