Troubleshooting

Image not rendering

Image too large

If the image is not rendering, it may be too large.

• If you are including a full size external <img> element, consider passing the external image as a string instead:

return {
  image: "https://example.com/image.jpg",
};

• Try resizing it to a smaller size via the imageOptions of the returned FrameDefinition.

return {
  image: <div>...</div>,
  imageOptions: {
    width: 100,
    height: 100,
  },
};

Image wrong format

If the image is not rendering, it may be in the wrong format. SVG images are typically not supported on mobile.

Initial frame not loading

Ensure that the fetchMetadata URL is correct and that it is inside the other property for Next.js.

VERCEL_URL environment variable

If you are using Vercel, the VERCEL_URL environment variable is not a fully qualified URL and may cause issues with fetchMetadata. You will have to prepend the protocol to VERCEL_URL.

export async function generateMetadata() {
  const frameMetadata = await fetchMetadata(
    new URL(
      "/frames",
      process.env.VERCEL_URL
        ? `https://${process.env.VERCEL_URL}`
        : "http://localhost:3000"
    )
  );
 
  return {
    title: "My page",
    other: {
      ...frameMetadata,
    },
  };
}

Vercel authentication

When deploying to Vercel, your site will not automatically be accessible to the public. You will need to disable Vercel Authentication under your project's Settings > Deployment Protection > Vercel Authentication on vercel.com.

Import type errors

If you are getting type errors when importing frames.js, you may need to change the moduleResolution in your tsconfig.json from node to nodenext.

{
  "compilerOptions": {
    "moduleResolution": "nodenext"
  }
}

Unable to access frame message on initial frame

The initial frame is accessed via a GET request and does not have access to frame message and hence user data.

Type error: Route ... does not match the required types of a Next.js Route

If you are getting this error you are exporting something other than a Next.js route from a route.tsx or page.tsx file.

We recommend creating a new file for your frames app and importing it in the routes that use it.

Example

Frames app file

import { createFrames } from "frames.js/next";
 
export const frames = createFrames({
  basePath: "/frames",
});

Initial page route

import { frames } from "./frames";
 
export const GET = frames(async (ctx) => {
  // ctx.message is not available in the initial frame
  return {
    image: <div>...</div>,
    buttons: [
      <Button action="post" target="/my-route">
        Next
      </Button>,
    ],
  };
});

Frame action handler route

import { frames } from "../frames";
 
export const POST = frames(async (ctx) => {
  // Do something with ctx.message
  // ...
 
  return {
    image: <div>...</div>,
    buttons: [
      // ...
    ],
  };
});

TypeError: Invalid URL ... when calling Next.js route

If you are getting this error you are possibly running your app behind multiple proxies. Next.js receives multiple x-forwarded-proto and x-forwarded-host headers which causes the URL to be invalid.

We recommend downgrading to next@14.0.1 as this is the last version that does not have this issue and works with frames.js. See https://github.com/framesjs/frames.js/issues/319 and https://github.com/vercel/next.js/issues/58914.

Combining old and new SDKs

You cannot use the <FrameComponent>, <FrameButton> and <FrameImage> components from the old SDK (frames.js/next/server) with the new SDK (frames.js/next).

The new SDK uses a FrameDefinition object to define a frame.