Run functions locally
Start the local Rayfin Functions host with rayfin dev, route frontend calls, attach a debugger, and troubleshoot local host errors.
Run functions locally when you need fast edits, local logs, and a Node debugger while the managed Rayfin backend stays deployed in Fabric.
Note
Functions are generally available in Rayfin 1.36 and are not available in every Fabric region or tenant.
Choose the local command
| Command | Use it when |
|---|---|
npx rayfin dev | You want the normal development loop: Fabric backend, local frontend, and local Functions host together. |
npx rayfin dev functions apply | You want to run only the local Functions host and start the frontend yourself. |
Both commands use services.functions.path from rayfin.yml, run the configured buildCommand, keep a typegen watcher running, and start Azure Functions Core Tools.
Prerequisites
services.functions.enabled: trueinrayfin/rayfin.yml.- An active Fabric deployment from at least one
npx rayfin up. - Node.js 20 or later.
- Azure Functions Core Tools on
PATH. @microsoft/fabric-user-data-functionsat the same version as the CLI —2.0.0for Rayfin 2.0. See Match the worker package to the CLI. Changed in 2.0- A local functions
host.jsonwhose PreviewextensionBundle.versionrange starts at 4.49.0 or later:[4.49.0, 5.0.0). Changed in 1.36.2
rayfin dev functions apply checks Node and Core Tools. If Core Tools is missing and the session is interactive, it asks for consent before installing. In non-interactive mode it prints the commands to run and stops.
Start only the Functions host
npx rayfin dev functions applyCommon options:
| Option | Default | Description |
|---|---|---|
--port <port> | 7071 | Port for the local function host. If the requested port is in use, the CLI uses the nearest free port. |
--inspect-port <port> | 9229 | Node inspector port used by the generated VS Code attach configuration. |
--no-debug | Debugging enabled | Disable the Node inspector. |
--no-emit-env | Emits env files | Do not regenerate framework .env.local from rayfin/.env. |
--verbose | false | Show detailed diagnostic output. |
--json | false | Emit JSON output. |
-y, --yes | false | Run without interactive prompts. |
The command does not start the frontend. Start Vite separately, or use npx rayfin dev to start both.
Route frontend calls to the local host
The Vite adapter from @microsoft/rayfin-local-dev forwards the SDK's default /functions/<name>/invoke route to the local Functions host that rayfin dev or rayfin dev functions apply selected. When no local Functions host is configured, it forwards the route to the configured Fabric backend instead, so a frontend-only session still runs the deployed functions. Changed in 2.0 When a configured local host is down, the adapter returns HTTP 502 rather than calling deployed code. See Calling functions from your app.
What the CLI writes
rayfin dev functions apply merges CLI-managed values into rayfin/functions/local.settings.json:
{
"IsEncrypted": false,
"Values": {
"AZURE_FUNCTIONS_ENVIRONMENT": "Development",
"RAYFIN_API_URL": "https://<deployed-app>",
"RAYFIN_PUBLISHABLE_KEY": "pk_...",
"RAYFIN_FABRIC_WORKSPACE_ID": "<workspace-id>",
"RAYFIN_FABRIC_ITEM_ID": "<item-id>",
"languageWorkers__node__arguments": "--inspect=9229"
}
}It also writes RAYFIN_PUBLIC_FUNCTIONS_URL=http://localhost:<port> to rayfin/.env and regenerates the framework .env.local unless --no-emit-env is passed.
Debug with VS Code
With debugging enabled, the CLI writes or updates a .vscode/launch.json configuration named Functions: Attach. Attach to the inspector port shown in the command output. Pass --inspect-port <port> to choose a different port, or --no-debug to run without an inspector.
When the requested inspector port is unavailable and the CLI slides to another port, Rayfin 1.36.1 and later keep an existing Functions: Attach entry in sync with the selected inspector port. JSONC launch files and --no-debug runs are left untouched. Changed in 1.36.1
Use local automatic sign-in
When a Vite app uses rayfinLocalDev() and a backend URL resolves, the adapter can seed local authentication from the developer's rayfin login session.
Protected static sites (services.staticHosting.assetAccess: protected) enable this automatically. Public sites enable it only when the adapter is configured with rayfinLocalDev({ autoLogin: true }). The adapter exposes a loopback-only /.rayfin/dev/session-token endpoint, obtains a delegated Entra token through the Rayfin CLI sign-in session, exchanges it for a Rayfin token response, and frontend code can install that response with signInWithBrokeredToken() from @microsoft/rayfin-auth-provider-fabric. The exchange requires services.auth.fabric.externalEntraExchange: true; see Develop locally.
Use isRayfinLocalAutoLoginEnabled() from @microsoft/rayfin-local-dev when frontend code needs to know whether that local-only flow is active. The behavior is for local development only; deployed Fabric sign-in still follows the app's normal auth configuration.
Use local secrets
Local functions do not receive the deployed secret bag. Add local-only secret values under Values in local.settings.json; ctx.Secrets.<NAME> falls back to process.env[NAME].
{
"IsEncrypted": false,
"Values": {
"THIRD_PARTY_API_KEY": "local-development-value"
}
}The CLI preserves keys you add when it merges its own values.
Use hot reload
Fresh 1.36 scaffolds include a build:watch script. During rayfin dev or rayfin dev functions apply, the CLI:
- Runs the initial functions build.
- Starts the package's
build:watchscript when present. - Starts a
[typegen]watcher forsrc/types.ts. - Starts
func startagainst compiled output.
If build:watch is missing, the CLI warns and starts the host without a compiler watcher. Rebuild manually after source edits. If the compiler watcher exits, the local session stops rather than serving stale code.
Rayfin 1.36.1 and later condense Azure Functions host restart noise to a single Functions host restarted. line. Changed in 1.36.1
Upgrade an existing functions host.json
rayfin functions init writes the local functions host.json used by Azure Functions Core Tools. Existing apps are not migrated when the scaffold changes, and Core Tools can reuse a cached extension bundle within the configured version range without checking for a newer bundle.
Since Rayfin 1.36.2, the local host.json should require the Preview extension bundle floor [4.49.0, 5.0.0). That bundle lets the local host sign you in when it has no terminal window, which matters when a coding agent starts rayfin dev. The package is under services.functions.path in rayfin.yml; the default is rayfin/functions/.
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
"version": "[4.49.0, 5.0.0)"
}
}Keep the other settings in your host.json unchanged; Core Tools downloads a matching bundle the next time the host starts. This local file affects npx rayfin dev and npx rayfin dev functions apply. Deployment is unaffected: rayfin up substitutes the CLI's deploy-time host.deploy.json, which uses the stable Microsoft.Azure.Functions.ExtensionBundle range [4.38.1, 5.0.0).
Rayfin 2.0 checks this for you: before starting the host, rayfin dev and rayfin dev functions apply print a warning when host.json still allows a Preview bundle older than 4.49.0. They never edit the file. New in 2.0
rayfin/functions/host.json allows Functions extension bundles older than 4.49.0, which can fail local sign-in, for example when the Functions host has no terminal window. Set "version": "[4.49.0, 5.0.0)" under extensionBundle.Troubleshoot local runs
Functions service is not enabled. Set 'services.functions.enabled: true' in rayfin.yml and re-run.
Run npx rayfin functions init, or add services.functions.enabled: true and services.functions.auth.type: application to rayfin/rayfin.yml.
No active deployment found. Run 'rayfin up' to deploy your Rayfin item first.
Run a full npx rayfin up. Local Functions need the deployed endpoint and publishable key.
Node.js >= 20 is required. Please upgrade your Node runtime and re-run.
Install or select Node.js 20 or later before starting the local host.
Missing Functions prerequisites. Run the following commands, then retry:
Install the listed prerequisites. In an interactive terminal, rerun without --json and without -y if you want the CLI to ask for consent and install Core Tools.
Azure Functions Core Tools still not detected after install
Open a new terminal so the installer-updated PATH is visible, then rerun the command.
Local sign-in fails without a terminal window
When a function declares an audience on its RayfinContext annotation, the local Functions host signs you in as it starts so it can provide ctx.Tokens. It reuses a cached sign-in when it can and prompts otherwise — for example, the first time it runs on a machine. A Preview extension bundle older than 4.49.0 cannot show that prompt when the host has no terminal window, such as when a coding agent runs npx rayfin dev: Core Tools logs A window handle must be configured and exits.
Rayfin 2.0 recognizes this failure: rayfin dev and rayfin dev functions apply replace their generic hint with the fix and name the file to change. New in 2.0
The Functions host could not sign in without a terminal window. Set "version": "[4.49.0, 5.0.0)" under extensionBundle in rayfin/functions/host.json, then retry `rayfin dev functions apply`.Update host.json as shown in Upgrade an existing functions host.json, then retry.
The installed @microsoft/fabric-user-data-functions@<version> ... but this CLI writes '3.0'.
The functions package still uses a worker older than the CLI, so type generation stops before it writes any files. Run the npm install @microsoft/fabric-user-data-functions@2.0.0 command the CLI prints, in the functions package, then restart the session. See Match the worker package to the CLI.
HTTP 502 from a local function call
The Vite adapter has a local Functions host configured, but the host is unavailable. Start or restart npx rayfin dev or npx rayfin dev functions apply. The adapter does not fall back to deployed function code while local routing is configured; this applies to both the default /functions/<name>/invoke proxy and the /.rayfin/api/<name> proxy used with an explicit functionsBaseUrl. When no local host is configured at all, the default route goes to the deployed backend instead. Changed in 2.0
Raw SQL access is not available when running locally
Expected: functions that use ctx.sql run only when deployed, because the service issues the SQL ticket only for deployed invocations. Deploy with npx rayfin up and test against the deployed app. See Raw SQL in functions.
In my Rayfin 2.0 project, start a local Rayfin Functions debugging session.
Confirm services.functions.enabled is true and services.functions.auth.type is application in rayfin/rayfin.yml. Confirm the app has been deployed at least once with `npx rayfin up`. Confirm the functions package depends on @microsoft/fabric-user-data-functions at the same exact version as the Rayfin CLI; if the CLI reports that the installed worker cannot read runtime metadata schema 3.0, run the `npm install` command it prints in the functions package. If the functions host.json allows a Preview extension bundle older than 4.49.0, set extensionBundle.version to `[4.49.0, 5.0.0)` before starting Core Tools. Run `npx rayfin dev functions apply` with the default port and debugger unless I ask for different ports. If Azure Functions Core Tools is missing, ask for terminal consent through the CLI flow rather than installing silently. Verify that RAYFIN_PUBLIC_FUNCTIONS_URL is written to rayfin/.env, explain how the Vite frontend reaches local functions through the adapter's default `/functions/<name>/invoke` proxy, or through `/.rayfin/api/<name>` when `functionsBaseUrl` is set, and tell me how to attach VS Code using the "Functions: Attach" configuration.Bulk import from CSV
Build a CSV import on a Rayfin function — pasted-text UI, server-side parsing and per-row validation, idempotent reference lookups, owner stamping, and an imported/rejected result.
Deploying functions
Deploy Rayfin functions with rayfin up or deploy only function code, fix a 404 from functions deploy, skip function deploys, and understand packaging and validation.