FAQ and troubleshooting

Before you buy#

Can I run it as a SaaS with the Regular License?#

Only if your end users are not charged. The Envato Regular License covers one end product whose users do not pay. If businesses pay you to use it (subscriptions, setup fees, any paid plan), you need the Extended License. See Envato's licence terms and Plans, billing and selling it as SaaS.

What are the server requirements?#

Node.js 20.9 or newer (22 recommended), PostgreSQL 13 or newer, HTTPS on your own domain, something that calls the job endpoint once an hour, and outbound email. It runs on Vercel as shipped, or on any server that can run next start. As a starting point, 1 vCPU and 1 GB of RAM is enough to evaluate, and 2 vCPU with 2 to 4 GB is comfortable for a small SaaS; treat those as guidance. Full details: Requirements.

Is there a default admin login?#

No. There are no default accounts, no setup wizard and no platform admin panel. You sign up like any user and own your own workspace. Running the service (plans, trials, removing accounts) is done in Stripe and with a few SQL statements: see First admin and operator tasks. The only built-in login is the demo shop account, whose password is public. It is off in production unless you set DEMO_LOGIN_ENABLED=true.

Which keys do I need?#

Everything else is optional. Configuration lists every variable.

Does it use AI?#

No. Detection is rules-based: a catalogue of 534 vendors with descriptor patterns, interval checks and a confidence score. No data is sent to an AI provider, and there is no AI cost.

Does it work without connecting a bank?#

Yes. Manual add, the 48-tool quick-add list, the UPI mandate form and statement upload (CSV, XLSX or text-layer PDF) all work on every plan. Bank feeds and email scanning are Pro features.

Which banks and countries are supported?#

Bank feeds work through Plaid for the US and Canada. UK (TrueLayer) imports once and then stops syncing until reconnected; EU (Salt Edge) has not been tested against a live Salt Edge account; and India (Setu) cannot be started from the interface. Statement upload works everywhere, with dedicated formats for HDFC, ICICI, SBI, Axis, Kotak, Yes Bank and Relay. See Integrations.

Does it cancel subscriptions for the user?#

No. It drafts the cancellation email, links to the vendor's cancel page when it knows it, and records the saving when the user marks the tool cancelled.

Can I host it on Vercel?#

Yes, it ships with a vercel.json and an hourly cron. Check that your Vercel plan allows hourly cron jobs and a function duration long enough for the hourly job, and note that attachments need persistent storage that is not available there in 0.1.0. See Option A: Vercel.

Is there a Docker image?#

No Dockerfile ships in 0.1.0. Installation has an example that builds when the container starts, because the build needs the database.

Is there a demo?#

Yes: subsweep.app, with a one-click demo shop on the sign-in page. It is shared and reset when stale.

Can I rebrand it?#

Yes, you have the full source. The name "Subsweep" appears in the layout, components, email templates, the browser extension and the Stripe setup script, and colours are tokens in app/globals.css. Check what your licence allows for redistribution.

Troubleshooting#

Every page returns 500, or "Missing production env: ..." when building#

The build stops with this message, and a server started anyway answers every request with "Internal Server Error". One of DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL, ENCRYPTION_KEY or CRON_SECRET (or their aliases) is not set in the environment the command runs in. On your own server, put them in .env.production.local in the app folder; on Vercel, add them for the Production environment.

The build fails with ECONNREFUSED or a database error#

next build connects to the database while pre-rendering. Make sure DATABASE_URL points at a database the build machine can reach, and that the database is running.

/api/health returns 503#

The database cannot be reached. Check DATABASE_URL, that the database is running and accepts connections from the app, and the server log for the connection error.

Lines like relation "user" already exists, skipping in the log#

Harmless. The schema bootstrap runs CREATE TABLE IF NOT EXISTS when each server process starts, and Postgres reports the tables it skipped.

"Email not verified" when signing in#

With an email provider configured in production, email accounts must verify their address first. Open the verification email; if it did not arrive, check your SMTP or Resend settings and the server log for SMTP send failed or Resend send failed.

"Sign-up is unavailable because email delivery isn't set up"#

Production refuses email sign-up when neither SMTP nor Resend is configured, because it cannot verify the address. Configure outbound email (Configuration). If you accept accounts whose address is never verified, set ALLOW_UNVERIFIED_SIGNUP=true instead. Google sign-in is not affected.

Magic links or verification emails never arrive#

• With no email provider configured, nothing is sent. Development prints magic links in the server log as [subsweep] Magic link for ...; production refuses them with "Email sign-in links are unavailable because email delivery isn't set up."
• EMAIL_PAUSED=true stops all email.
• For Gmail SMTP, use an app password and keep SMTP_HOST=smtp.gmail.com, SMTP_PORT=465, SMTP_SECURE=true. On port 587, set SMTP_SECURE=false.
• For Resend, RESEND_FROM must use a domain verified in Resend.

Invites fail with "We couldn't send the invite email"#

The invite email could not be sent, so the invite was withdrawn. Fix outbound email and invite again.

There is no demo button, or "The demo shop is switched off"#

The demo shop is off in production unless DEMO_LOGIN_ENABLED=true, and while it is off the demo account's published password is refused. Set the variable and restart only if you want a public showroom (The demo account).

The hourly job returns 401#

The secret does not match. The endpoint checks JOB_SECRET if it is set, otherwise CRON_SECRET. On Vercel, Cron sends CRON_SECRET, so do not set a different JOB_SECRET there.

No reminders, alerts or digests#

• The hourly job is not being called, or returns 401.
• The workspace is on Free (its trial ended without an upgrade).
• No email provider is configured, so messages only appear in the log.
• Digests go out only during the chosen local hour on the 1st (monthly) or Monday (weekly).

"Bank connection is not available here" or "Plaid is not configured"#

The workspace's country has no bank provider (India and others), or the provider's keys are not set. In production there is no sample bank data to fall back on.

A later email scan or TrueLayer sync finds nothing new#

The access token stored at connect time has expired, and 0.1.0 does not refresh it, so the request quietly returns nothing. Disconnect and reconnect the mailbox or bank, then scan again.

Google sign-in or Gmail says redirect_uri_mismatch#

The redirect URI registered with Google must exactly match BETTER_AUTH_URL plus /api/auth/callback/google (sign-in) or /api/oauth/gmail/callback (Gmail), including https and with no trailing slash.

"Billing isn't available yet. Contact us..."#

STRIPE_SECRET_KEY is not set. Set the Stripe keys and price IDs (Stripe setup), or set the plan by hand.

Checkout fails with "Set STRIPE_PRICE_PRO_MONTHLY..."#

Stripe is configured but no price ID is set for that plan. Run npm run setup:stripe (it reads .env) or create the prices in Stripe and set STRIPE_PRICE_PRO_MONTHLY, STRIPE_PRICE_PRO_YEARLY and STRIPE_PRICE_ACCOUNTANT.

The plan did not change after checkout#

The webhook did not reach the app or was rejected. Check the endpoint URL (/api/webhooks/stripe) and that the four events are selected. Stripe's dashboard shows each delivery and its response: 503 means STRIPE_WEBHOOK_SECRET is not set, and 400 usually means the signature did not match, so check that the variable holds the signing secret of that endpoint.

"Adding clients needs an active Accountant plan"#

Add client works only while your own workspace is on the Accountant plan, and not from inside a client's workspace. Buy Settings → Billing → Accountant · 3 clients in your own workspace, or see Teams and accountants.

A PDF statement is refused#

Scanned image PDFs have no text to read. Export a CSV or XLSX from the bank instead, or download a text-based PDF. For a password-protected PDF, enter the password the bank uses for statements.

The app listens on the wrong port#

npm start uses port 3000 unless PORT is set or you pass -p to next start.