Tips & troubleshooting

Practices that lead to better Foundry functions, plus fixes for the most common issues you’ll hit when building and connecting integrations.

A grab-bag of advice and fixes from teams already using Foundry day-to-day. If something’s broken and you don’t see it here, the Foundry reference docs cover the exact behavior of each part of the product.

---

Tips for getting the most out of Foundry

Start with the narrowest scopes

It’s easier to add a scope later than to explain to a security review why you asked for the kitchen sink on day one. For Google, prefer the .readonly variants until you actually need to write.

Point the docs URL at the API reference

Research is much better when Foundry can see endpoint pages and OpenAPI specs. For Google APIs, link directly to the reference page for the specific API (Calendar, Gmail, and so on) rather than to developers.google.com.

Use one integration per real-world tool

Keeping Salesforce and HubSpot as separate integrations, instead of a single “CRM”, makes functions easier to understand and lets you swap one out without rewriting the other.

Test in development before publishing

Foundry’s test panel lets you pick the runtime environment. Wire your function against a sandbox tenant in development first so you don’t create real records while iterating.

Give your function a precise description

The description is what AI agents read when they decide whether to call your function. “Look up a customer by email and return their plan and ARR” is much more useful than “get customer data.”

Chat your way to better code

When something isn’t right, ask in plain language: “add pagination,” “retry on 429,” “only return active users.” It works far better than hand-editing the generated TypeScript.

Iterate small

Get the happy path working first, then ask Foundry to add error handling, pagination, or filtering one piece at a time. Each round leaves you with a working function.

Use Configure to keep agent prompts fresh

If you change what a function does, regenerate the AI tool prompt from the function’s Configure tab so agents pick up the new behavior.

All of the UI surfaces mentioned here (the test panel, the Configure tab, the workspace layout) are covered in the main Building functions reference.

---

Troubleshooting

Find your symptom, expand it for the fix.

OAuth setup

Google returns "redirect_uri_mismatch"

The redirect URI in your OAuth client doesn’t exactly match Ravenna’s callback URL. Confirm the right value with your Ravenna team and paste it back into Google verbatim. Trailing slashes and http vs https matter.

The OAuth flow succeeds but the function gets 401s

The API you’re calling probably isn’t enabled on the Google Cloud project. Go to APIs & Services > Library and enable it, then have the user click Reconnect on the integration to refresh their consent.

Tokens stop working after an hour

For Google, make sure access_type=offline and prompt=consent are set in the authorization URL parameters. Without them, Google doesn’t issue a refresh token and access expires when the access token does. See the Google walkthrough for the exact JSON.

A refresh token expired and functions started failing

This hits Okta and long-inactive Google connections most often. Use Reconnect on the integration, either from the connection row in Settings > Integrations or from the Authentication tab in the Foundry builder, to re-run the OAuth consent flow in place. The connection keeps its configured actions and settings, only the credentials are refreshed. See Reconnect a Foundry OAuth account.

A user disconnected and now functions fail for them

Have the user reconnect from Settings > Integrations under the Custom category. Their function picks the new connection up automatically.

Docs research

Research fails or returns nothing useful

The docs URL likely points at marketing content. Try the API reference page directly. If the tool has an OpenAPI or Swagger URL, use that instead.

Research finishes but generated code uses the wrong endpoints

Either point Foundry at a narrower docs URL (a specific endpoint page) or be more specific in your function description, naming the endpoint or method explicitly.

Generation and testing

Generation status is stuck on Error

Open the function workspace and check the error message. It’s usually a clue about a missing scope, a broken docs URL, or an incompatible response shape. Click Regenerate to try again after fixing the cause.

Test runs return data, but workflows show no output

Make sure the function returns a structured object, for example { id, status }, rather than a string. Workflows can only map fields off objects.

The function works in development but fails in production

Check that the credential you configured covers the production environment. Some tools issue separate keys per environment, and ctx.env gives the function a way to branch. The integration itself still needs to reach the production API.

Publishing

Publish fails on validation

Foundry runs TypeScript and dry-run checks before publishing. Read the error in the publish dialog, which points at the exact line. Ask in chat (“the publish check is failing because X, fix it”) rather than editing by hand.

Agents don't seem to know about a function I just published

New functions are picked up immediately, but if you changed what a function does, regenerate the AI tool prompt from the Configure tab. Agents use that prompt to decide when to call the function.

Still stuck? Reach out to your Ravenna team or [e-mail] with the function ID and the error you’re seeing.