Troubleshooting

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.

​

File processing issues

​

Machine files stuck in “processing”

Files normally process within minutes. If a file stays in processing for an extended period:

1. Check the file status endpoint — it shows the processing state for each pipeline step (standardGeojson, cleanupGeojson, summary, units, etc.).
2. Look for a specific step that shows failed with an error message.
3. 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:

1. Does the Leaf user have fields with active boundaries?
2. Do the machine files’ GPS coordinates fall within those boundaries?
3. 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

1. Confirm your alert URL is registered and active — list your alerts to verify.
2. Your endpoint must return a 2xx response. If it returns an error, Leaf retries with backoff but eventually stops.
3. Check that your server is publicly accessible. Leaf cannot reach localhost or private networks.
4. 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