FerreMarket Troubleshooting: Common Setup and Runtime Issues

Redirected to /admin/login on every page load

CauseThe AuthContext provider reads the current Supabase session on mount and starts in an undefined state while the async check is in flight. If VITE_SUPABASE_URL or VITE_SUPABASE_ANON_KEY are missing or incorrect, the Supabase client never resolves a session and the session value remains null. Any protected route that checks for a valid session immediately redirects unauthenticated users to /admin/login.Fix

Verify your environment variables

Open .env at the project root and confirm both Supabase variables are present and non-empty:

VITE_SUPABASE_URL = "https://xxxxxxxxxxxx.supabase.co"
VITE_SUPABASE_ANON_KEY = "your-supabase-anon-key"

Cross-check the values against Project Settings → API in your Supabase dashboard.

Restart the Vite dev server

Vite reads .env at startup. If you edited the file while the server was running, the changes are not picked up automatically. Stop the server with Ctrl+C and run npm run dev again.

Create a user in Supabase Auth

If the variables are correct but no user exists, log in to the Supabase dashboard, navigate to Authentication → Users, and create a user manually using Add user → Create new user. Then sign in through the FerreMarket login page.

Wait for the session to resolve

The session state in AuthContext is undefined while the initial supabase.auth.getSession() call is in progress — this is intentional to distinguish “not yet checked” from “definitely logged out”. Protected routes should render a loading indicator while session === undefined and only redirect when session === null. If you see an instant redirect with no loading state, the Supabase client initialisation itself is failing — check the DevTools console for a supabase client error.

Blank page after npm run dev

CauseA blank white page with no visible content almost always means the React application failed to mount. The most common cause is that the Supabase client module throws during import because VITE_SUPABASE_URL or VITE_SUPABASE_ANON_KEY resolved to undefined — which happens when the .env file does not exist or has not been populated.Fix

Check that .env exists

From the project root, confirm the file is present:

ls -la .env

If the file is missing, create it by copying the example:

cp .env.example .env

Then fill in the required values before continuing.

Check the browser console for errors

Open DevTools (F12), click the Console tab, and look for a red error message. A message like createClient: supabaseUrl is required confirms the env var is not being read.

Restart the dev server

After saving changes to .env, stop the Vite dev server (Ctrl+C) and restart it:

npm run dev

Vite does not hot-reload changes to environment variable files.

Confirm the VITE_ prefix

Every variable in .env must begin with VITE_. Variables without this prefix are intentionally excluded from the browser bundle by Vite and will resolve to undefined at runtime.

PDF invoice generation fails

CauseFerreMarket uses jspdf and jspdf-autotable to generate invoice PDFs in src/pages/Reportes.tsx. If either package is missing from node_modules (e.g. after a partial install or a corrupted lockfile), the import throws at runtime and PDF generation silently fails or throws an uncaught error.Fix

Reinstall all dependencies

Run a clean install to ensure every package declared in package.json is present:

npm install

Confirm jspdf and jspdf-autotable appear in the output or verify they are in node_modules:

ls node_modules | grep jspdf

Check the browser console

Open DevTools and look for any error in the Console tab when you trigger PDF generation. Errors from jspdf or jspdf-autotable include the function name and a descriptive message that pinpoints whether the issue is in the library itself or in the data passed to it.

TypeScript errors on build

CauseThe project uses strict: true in tsconfig.app.json along with noUnusedLocals and noUnusedParameters, which means a wider class of code patterns are rejected compared to a default TypeScript setup. Common sources of errors include: type mismatches between Supabase query return types and component props, missing type declarations for a dependency, or implicit any in callback arguments.Fix

Run the type-checker directly

Get a full list of all type errors without triggering a build:

npx tsc --noEmit

TypeScript will print every error with its file path, line number, and a description. Fix all reported errors before running npm run build.

Check for missing @types packages

A common issue is that @types/luxon is absent from devDependencies. Confirm it is installed:

ls node_modules/@types | grep luxon

If it is missing, it should be present in package.json under devDependencies as "@types/luxon": "^3.6.2". Run npm install to restore it.

Review strict null checks

With strict: true enabled, TypeScript will not allow values that could be null or undefined to be used without a null check. The most common pattern in FerreMarket is checking whether a Supabase query returned data before passing it to a component. Add a guard such as if (!data) return or use optional chaining (data?.field).

Supabase Edge Function returns 404

CauseFerreMarket calls three Supabase Edge Functions — create-user, delete-user, and send-password-recovery-email — from the admin user management screens. A 404 response means the function URL was reached but no deployed function was found at that name. This happens when the functions have not yet been deployed to the Supabase project, or were deployed to a different project than the one referenced by VITE_SUPABASE_URL.Fix

Install and log in to the Supabase CLI

If you do not have the CLI installed, follow the official guide. Then authenticate:

supabase login

Link your local project to Supabase

From the project root, link to the remote project. Replace <project-ref> with the value found in Project Settings → General → Reference ID:

supabase link --project-ref <project-ref>

Deploy the Edge Functions

Deploy each of the three required functions:

supabase functions deploy create-user
supabase functions deploy delete-user
supabase functions deploy send-password-recovery-email

Confirm deployment

In the Supabase dashboard, navigate to Edge Functions and verify all three functions appear with a green status indicator. Then retry the operation in FerreMarket.

Product images not loading

CauseFerreMarket constructs product image URLs by prepending VITE_CLOUDFLARE_CDN_URL to the stored image path. If this variable is not set, all image src attributes resolve to an invalid URL and the browser shows a broken image icon. A secondary cause is that the Cloudflare R2 bucket exists but has not been configured for public access — requests to the CDN URL return 403 Forbidden.Fix

Set VITE_CLOUDFLARE_CDN_URL in .env

Add the public base URL of your R2 bucket to .env:

VITE_CLOUDFLARE_CDN_URL = "https://pub-xxxx.r2.dev"

Restart the Vite dev server after saving.

Enable public access on the R2 bucket

Log in to the Cloudflare dashboard, navigate to R2 → your bucket → Settings, and enable Public Access. Cloudflare will provide a pub-xxxx.r2.dev URL — use this as the value of VITE_CLOUDFLARE_CDN_URL.

Verify the URL in DevTools

Open DevTools, click the Network tab, filter by Img, and reload the page. Click on a failing image request to inspect the full URL. Confirm the domain matches your R2 public URL and the path matches an object that exists in the bucket.

Charts not rendering in Dashboard

CauseThe Dashboard page uses Recharts to display sales and inventory graphs. Recharts renders correctly with empty arrays — it simply shows blank chart areas — so chart components that silently receive no data can be hard to spot. The underlying cause is almost always a Supabase query error: the productos, clientes, or ventas tables do not exist, have different column names than expected, or the anon key does not have SELECT permissions due to a missing Row Level Security policy.Fix

Check the browser console for Supabase errors

Open DevTools → Console. Any failed Supabase query logs an object containing { error, status, statusText }. The error.message field tells you exactly which table or column is the problem.

Verify the required tables exist in Supabase

In the Supabase dashboard, navigate to Table Editor and confirm the following tables are present with the expected schemas:

productos — product catalog (name, price, stock, category, etc.)
clientes — customer records (name, email, phone, etc.)
ventas — sales transactions (date, total, client reference, etc.)

If any table is missing, run the SQL migration scripts from the supabase/migrations/ directory (if present) or create the tables manually.

Check Row Level Security policies

Navigate to Authentication → Policies in the Supabase dashboard. Each table that the anon key needs to read must have a SELECT policy that allows public or authenticated access. Without a permissive policy, queries return an empty result set rather than an error, which produces blank charts.

Test queries directly

Use the SQL Editor in the Supabase dashboard to run the same queries the dashboard uses:

SELECT * FROM ventas LIMIT 10;
SELECT * FROM productos LIMIT 10;
SELECT * FROM clientes LIMIT 10;

If these return data in the dashboard editor but not in the app, the issue is with RLS policies and the anon key role.

Getting Started

Core Modules

Administration

Deployment