Troubleshooting and questions

#Installing

Messages from the launcher and the black install window, the first time you set the app up.

#"Please extract the ZIP first" or "Some files are missing"

You may see: "Please extract the ZIP first", "Some files are missing", "The _system folder is not next to this launcher", "_system folder is missing. Please re-extract the ZIP or re-download from billing.reazix.com." (Mac and Linux), "Missing file: start-windows.ps1" or "Could not find start-windows.ps1".

The launcher was opened from inside the ZIP, or the ZIP was only partly extracted, so the rest of the app is not next to it.

1. Close the launcher.
2. Right-click the ZIP and choose Extract All….
3. Open the extracted Reazix-Billing folder and double-click the launcher there. Keep the launcher and the _system folder together.
4. Still missing? Download the ZIP again; the download may have been cut short.

See Step 2: Unzip (extract) it.

#"Windows protected your PC"

Windows shows this the first time for any program without a paid certificate. Nothing is wrong.

1. Click More info, then Run anyway.
2. If it still will not open, right-click the launcher, choose Properties, tick Unblock and click OK.

See "Windows protected your PC".

#The install stopped with an error

The black window shows PROBLEM: and what went wrong. Fix it, then click Install again; it carries on where it stopped.

• "The app cannot reach the internet to download its packages", "Could not download Node.js" or "The download did not work": the first install needs the internet. Check the connection (open any website). On an office network, a proxy or firewall may block it; ask whoever runs the network to allow registry.npmjs.org and nodejs.org.
• "The app packages did not install": the internet, disk and folder look fine, so antivirus is the usual cause. Add the Reazix-Billing folder to its exclusions and click Install again.
• "Node.js could not be set up automatically": install Node.js LTS yourself from nodejs.org (the page opens by itself), keep the default options, and open the launcher again. If antivirus removed it, add the folder to its exclusions.
• "Windows can install Node.js LTS for this PC ... Install Node.js LTS now?": the app could not download Node.js itself, so it offers Windows' own installer. Type Y and press Enter to accept (Windows may ask for permission), or anything else to install it yourself.
• "This version of Windows is too old": the app needs Windows 10 or 11. Node.js no longer runs on Windows 7 or 8.
• "The app cannot write to its own folder": see The app is not allowed to write.
• "Drive C:\ is almost full": the install needs about 400 MB. See The disk is full.
• "too old", npm ERR! or "Unsupported engine": see Node.js is too old.
• "Reazix Billing is already installed on this computer": see Already installed on this computer.

Never delete the data folder to fix an install.

#"Already installed on this computer"

You may see: "Already installed on this computer" in the launcher, or "Reazix Billing is already installed on this computer, in: ..." in the black window.

You extracted a new ZIP into a new folder. Your invoices are in the copy it names, so it does not make a second, empty copy.

1. Click Update the installed copy. It uses the files you just extracted, so no download is needed.
2. When it finishes, open the app from your Reazix Billing shortcut as usual.
3. The new folder is not needed after that. You can delete it.

#"Node.js is too old" or "npm ERR!"

You may see: "The Node.js v... on this PC is too old for this app", "Node.js v... on this machine is too old", "npm ... on this machine is too old", "Unsupported engine", npm ERR!, a file named npm-debug.log, or "SyntaxError: Unexpected token" when the app starts.

The app runs on Node.js 18 or newer (with npm 7 or newer). An older Node.js on the computer cannot install or run it.

1. Windows, v1.10.81 or newer: click Install or Open App again, with the internet on. The app fetches a current Node.js into its own folder by itself (about 30 MB, once) and leaves your other Node.js alone.
2. Windows, older version: install Node.js LTS from nodejs.org, delete the _system\node_modules folder (the _system folder is hidden: in File Explorer, View → Show → Hidden items), and click Install again.
3. Mac: install the LTS macOS Installer (.pkg) from nodejs.org, or run brew install node@20, then open the launcher again. See Part 1: Install Node.js.
4. Linux or NAS: install Node.js 20 with the commands in Step 1: Install Node.js 20 (the window also prints the command for your system), then start the app again.

Only the node_modules folder may be deleted. Never delete the data folder.

#Starting the app

The launcher or the browser cannot reach the app, or the app asks for a PIN.

#"Still starting..." or "The server has not answered in 90 seconds"

You may see: "Still starting... (30 seconds. The first start after an update is the slow one.)", "The server has not answered in 90 seconds", or, on versions before v1.10.69, "Server did not respond in 15s".

The first start after an install or update is slow, because antivirus checks every new file.

1. Wait a minute, then open http://localhost:47371 in your browser.
2. If it does not open, close the black window and click Open App again. From v1.10.81 this also finishes an install that an update left half done.
3. If the window shows a PROBLEM: above that line, the entries under The install stopped with an error say what to do.
4. Still nothing? The reason is written in the errors.log file in the data folder, on a line with Failed to start server. Send it with your report.

#"Failed to fetch", "App Not Running" or "Needs a Quick Start"

You may see: "Failed to fetch" (Chrome, Edge), "NetworkError when attempting to fetch resource" (Firefox) or "Load failed" (Safari), often after words like Restore failed: or Export failed:; a red dot on Control Panel in the menu; a page saying "Reazix Billing Software Needs a Quick Start"; "Could not check the PIN. Is the app still running?"; or the browser's own "This site can't be reached" or a blank page.

The app's engine (the server on your computer) is not running: the computer was restarted, the app was stopped, or it closed. Nothing already saved is lost.

1. Double-click the Reazix Billing icon on your Desktop or in the Start menu (Mac: Reazix Billing - MAC; Linux: the start command in Step 3). It starts the app if needed and opens the right address. If a small launcher window opens instead (an install from before version 1.10.83, the first time), click Open App.
2. Wait up to a minute. The "Needs a Quick Start" page carries on by itself once the app is running; otherwise press F5 to reload.
3. Try what failed again.

You never need to type the address yourself. If it keeps stopping, see Port is busy and the Problem log.

#"Port 47371 is busy" or "address already in use"

You may see: "Port 47371 is busy, trying 47372...", EADDRINUSE or "address already in use". These lines only appear when the app is started from a Terminal or Command Prompt.

Another program, or a second copy of Reazix Billing, already uses that port (the "door" the browser knocks on). The app picks the next free one by itself and saves it in data\port.txt; the launcher reads that file, so Open App goes to the right address.

1. Always open the app with its Reazix Billing icon (or the launcher's Open App), not a bookmark of localhost:47371, which may now be the other program.
2. If the launcher says it has not answered, close it and click Open App once more: it reads the new port.
3. The Control Panel shows the port the app is using.
4. Two copies of the app on one computer? Keep using the one with your invoices; see Already installed.

#PIN problems: "Wrong PIN" or a forgotten PIN

You may see: "Wrong PIN. Try again.", "Too many wrong tries. Wait 30 seconds and try again." (after 5 wrong PINs in a row), "Could not check the PIN. Is the app still running?", or in Settings "Current PIN is wrong", "The two PINs do not match", "The PIN must be 6 digits" (or 8).

The PIN lock asks for the PIN once per browser tab. "Could not check the PIN" means the app is not running: see Failed to fetch.

Forgot the PIN? It can be removed on this computer without losing anything:

1. Open the Reazix-Billing folder, the one with the launcher in it.
2. Make a new empty file there named RESET-PIN. On Windows: right-click an empty space, New → Text Document, and name it RESET-PIN (RESET-PIN.txt also works). On a Mac or Linux, in the Terminal: touch ~/Reazix-Billing/RESET-PIN (change the path if your folder is elsewhere).
3. Reload the app's page. The PIN is removed and the file deleted by itself. Your invoices are not touched.
4. Set a new PIN in Settings if you want one.

#Updating

Problems during or right after an update. An update never changes your data folder, and backs it up first.

#An update went wrong

You may see: "Update failed — ..." in the app, "ERROR: could not reach billing.reazix.com. Are you online?", "Could not check for updates. Check internet connection.", or "The new version is in place, but it is not ready to run yet".

Your data folder is never changed by an update, and a backup was saved in Documents\Reazix Billing Backups before it started.

1. Check the internet, then run the update again. This fixes most problems.
2. If the window showed a PROBLEM:, fix that first (see The install stopped with an error), then click Open App: it finishes the install by itself.
3. If it still fails, update by hand with the ZIP: see Windows: other ways.

#"Update complete", but the old version is still there

You may see: "[OK] Update complete! Restart the app (Stop Server -> Open App) to run the new version." or "Update finished. Reload the page to use the new version."

The new files are in place, but the running app or your browser still has the old version.

1. Press Ctrl + F5 (Mac: ⌘ + Shift + R).
2. Still the old number at the bottom of the Dashboard? Stop the app (launcher, More options → Stop the app, or Stop Server in the Control Panel), then click Open App.
3. If the app does not start after that, see The server has not answered.

#"Failed to fetch dynamically imported module"

You may see: "Failed to fetch dynamically imported module", "error loading dynamically imported module" or "Loading chunk ... failed", or a screen that will not open after an update.

The browser kept parts of the old version after an update. The app normally reloads itself once to fix this.

1. Press Ctrl + F5 (Mac: ⌘ + Shift + R).
2. If it comes back, close every tab of the app, then open it again from its Reazix Billing icon.

#"Update and backup scripts not found" or "Not available here"

You may see: "Update and backup scripts not found." in the Control Panel, buttons that say Not available here, or "Not available here: the script for this action is not in the app folder. Download the latest ZIP to get it."

The Control Panel runs scripts that come with the downloaded ZIP, and they are not in this copy. On Mac and Linux only Update and Backup have scripts, so Restore, Move and Stop always say Not available here.

1. Update with the launcher's More options → Update to the latest version, or by hand with the downloaded ZIP.
2. For your data in the meantime, use Export Backup in Settings.

More in "Update and backup scripts not found".

#Saving and working in the app

Messages while making invoices, saving settings or importing.

#"This screen ran into a problem. Your data is safe."

One screen of the app hit an error and was stopped, so the rest of the app keeps working. Nothing that was already saved is lost.

1. Click Try again.
2. If the panel comes back, click Go to Dashboard and carry on with other work.
3. Click Report this problem so it gets fixed. The report is filled in for you, and private details (GSTIN, PAN, phone, email, UPI ID and bank account numbers) are removed before it leaves. You can read it before you send it.

#"Invoice number ... already exists"

You may see: "Invoice number INV/0007 was already used — saved as INV/0008 instead.", "Invoice number ... already exists. Change it before saving.", "Invoice number ... is already used by another invoice. This invoice is still saved as ...", "A bill with this invoice number already exists", or "An invoice with this number exists again. Rename or delete it first." (restoring from the trash).

Two invoices cannot share a number, and the app never overwrites the other one. A new invoice simply moves on to the next free number by itself.

1. For an invoice you are editing, change the number in the invoice details to one that is not used, and save again.
2. To find the other invoice, search its number with Ctrl + K.
3. "Could not find a free invoice number after 1000 attempts": type a number yourself, or set Start numbering from in Settings past your last invoice.

#"Request body too large"

Usually after Failed to save, Restore failed: or Import failed:.

Something you saved was bigger than the app accepts in one go: up to 5 MB for an everyday save, up to 500 MB for restoring a backup file. The usual cause is a very large logo, signature or stamp picture, because every invoice keeps a copy of your business details with their pictures.

1. Make the picture smaller, ideally under 500 KB: crop it to just the logo or signature, or save it as a JPG. A free site such as tinypng.com can shrink it.
2. Upload the smaller picture in Settings and save.
3. Try what failed again.
4. For a backup file over 500 MB, restore a daily backup from Settings, Backup Management, or the ZIP with Choose Backup ZIP in the Control Panel.

#"The disk is full"

You may see: "The disk is full", ENOSPC, "no space left on device", "Drive C:\ is almost full" (install), or "the disk is full" in an update message.

The drive the app is on has no free space, so the app could not write. The app writes each file in full or not at all, so nothing already saved is lost or half-written.

1. Free some space: empty the Recycle Bin (Mac: Bin), delete old downloads and videos you do not need.
2. Backups you have already copied somewhere else can be deleted from Documents\Reazix Billing Backups.
3. Try again.

#"The app is not allowed to write to its data folder"

You may see: "The app is not allowed to write to its data folder", "The app cannot write to its own folder" (install), EACCES, EPERM, "permission denied" or "operation not permitted".

Windows or antivirus is stopping the app from changing its own files. Usual causes: the app folder is inside C:\Program Files, on a read-only or synced drive, or antivirus Controlled folder access blocks it.

1. Stop the app (launcher, More options → Stop the app).
2. Move the whole Reazix-Billing folder to Documents or D:\, and open the launcher from there. The old Desktop shortcut points at the old place: right-click the launcher → Send to → Desktop (create shortcut) for a new one.
3. If antivirus blocks it, allow the app: in Windows Security → Virus & threat protection → Ransomware protection, use Allow an app through Controlled folder access, or add the folder to your antivirus's exclusions.
4. Mac or Linux: the folder may belong to another user (for example after using sudo). In the Terminal: sudo chown -R $(whoami) ~/Reazix-Billing (change the path if your folder is elsewhere).

#A CSV import did not work

You may see: "CSV file is empty or has no data rows", "Failed to parse CSV file", "Could not read ...", "Import stopped after ...", or for bank statements "Could not parse this CSV" or "No transactions found".

The file is not a plain CSV, or its first row is not the column headings.

1. In Excel, use File → Save As → CSV (Comma delimited). An .xlsx file renamed to .csv does not work.
2. Keep the column headings in the first row and the data from the second row down.
3. After "Import stopped after ...", the rows before it are saved. Fix the row the message names and import the rest.
4. For bank statements, use the CSV straight from your bank's download, not one edited by hand.

See clients, products, purchases and bank statements.

#Reading a bill photo failed

You may see: "OCR failed: ...", "Please upload an image (PNG, JPG, WebP)." or "Image is over 8MB".

1. Use a sharp, straight, well-lit JPG or PNG under 8 MB, cropped to the bill.
2. If the message mentions fetch, network or worker, press Ctrl + F5 and try again; if it persists, see Failed to fetch.
3. If it still fails, enter the bill by hand.

#Printing and PDFs

Print does nothing, or the PDF is not right.

#Print does nothing, or "Print failed"

You may see: "Your browser blocked the print window. Allow pop-ups for this app and try again.", "Allow pop-ups for this page to print the report", "Print failed — try Download PDF instead", "Failed to generate PDF." or "Could not generate any PDFs".

1. Allow pop-ups for the app: click the blocked pop-up icon at the right end of the address bar, choose Always allow for localhost, and try again.
2. Use Download PDF and print the PDF instead.
3. Press Ctrl + F5 and try again.

For receipt printers, see Receipt printer problems.

#"Its PDF in Saved Invoices could not be updated"

You may see: "Invoice saved, but its PDF in Saved Invoices could not be updated. Use Save & Download." or "A saved PDF could not be marked CANCELLED. Close the PDF if it is open, then cancel again."

The invoice itself is saved. Only its PDF copy could not be replaced, usually because that PDF is open in a PDF reader.

1. Close the PDF in Adobe Reader, Edge or your browser.
2. Click Save & Download again, or repeat the cancel or undo.

#Something is missing from the PDF

• Logo, signature or stamp: check it is uploaded and saved in Settings, and ticked under Customize.
• UPI QR code: needs a UPI ID on the account, a rupee invoice, and UPI QR ticked under Customize.
• Bank details or PAN: tick Bank details under Customize; the account needs a bank name.
• Anything on a receipt printer: receipts leave some things out on purpose. See What a receipt leaves out.

#A logo or signature picture will not upload

You may see: "This doesn't look like an image", "Image is ... MB — over the 5MB cap", "Image too large (max 2MB)", "Image too large (max 3MB)", "Image must be under 500KB", or "Could not decode this image".

1. Use a PNG or JPG. An iPhone photo (HEIC) must be turned into a JPEG first: share it to Files as a JPEG, or on the iPhone set Settings → Camera → Formats → Most Compatible for new photos.
2. Make it smaller, ideally under 500 KB: crop it or shrink it with a free site such as tinypng.com.
3. Upload it again.

#GST, tax and returns

Wrong tax on an invoice, and messages from GST Returns.

#The invoice has the wrong tax split

1. Check your own state in Settings.
2. Check the client's state, or their GSTIN, which fills the state in.
3. If goods go to a different state from the client's address, set Place of Supply on the invoice.
4. For a client abroad, set their country: it is then an export, charged as IGST. For an SEZ unit, tick SEZ on the client.

See How GST is worked out.

#"Set your business State in Settings"

You may see: "Set your business State in Settings — required for correct CGST/SGST vs IGST split." or "Set your GSTIN in Settings first" (E-Way Bill).

The app needs your state to choose CGST + SGST or IGST, and your GSTIN for E-Way Bill files.

1. Open Settings, Company Details.
2. Fill in State (and GSTIN, which fills the state in), and save.
3. Go back to the invoice; the tax is worked out again.

#No GST is charged at all

The Tax % column is probably turned off under Customize. Turning it off removes GST from the invoice, and your choice carries over to new invoices. Tick it again. Bills of supply and delivery challans never charge GST.

#"GSTR-1 export blocked — fix these first"

You may also see "GSTR-1 JSON exported. ⚠ ...": the file was made, with warnings worth reading.

An invoice number is too long or has characters the portal refuses, or an item has a GST rate the portal does not accept. The message names the first ones.

1. Open the invoice the message names and fix its number or rate.
2. Export again.

See Checks before the file is made.

#"That doesn't look like a GSTR-2B JSON"

You may see: "That doesn't look like a GSTR-2B JSON. Expected docdata.b2b array." or "Failed to parse GSTR-2B JSON".

The file chosen is not the GSTR-2B JSON from the GST portal: often the Excel or PDF version, or a different return.

1. On the GST portal, download GSTR-2B for the month as a JSON file.
2. If it comes as a ZIP, extract it first.
3. Choose that .json file. See GSTR-2B.

#"No data to export for this period"

You may see: "No data to export for this period", "No invoices to export", "No B2B data to export", "No TDS entries in this period", or "Nothing to export".

The chosen period has nothing of that kind for this business.

1. Check the period at the top.
2. Check the business at the top of the sidebar: each business has its own invoices. See Switching business.

#It says VAT instead of GST, or the other way round

Change Region in Settings, and check your country in Company Details. Tax names follow the seller's country.

#Backups, restore and Google Drive

Daily backups, backup files and restoring.

#A backup or restore failed

You may see: "This file doesn't look like a Reazix Billing backup.", "Could not read the file", "Import failed: ...", "Restore failed: ...", "Backup failed: ..." or "No data folder found - nothing to back up."

A restore saves what you have now first, so a failed one changes nothing.

1. Read the end of the message: Failed to fetch, Request body too large, disk full and permission each have their own entry.
2. For Import Backup, choose the reazix-backup-date.json file saved by Export Backup. A ZIP from the launcher or Control Panel is restored with Choose Backup ZIP in the Control Panel instead.
3. Try another day from Settings, Backup Management.

See Backups and updates.

#"Cannot write to that folder" (backup copy folder)

You may see: "Give the full folder path, for example D:\Backups", "Choose a folder outside the app's data folder.", "Cannot write to that folder: ...", or "Folder saved, but copying today's backup failed: ...".

1. Type the whole path, starting with the drive letter, such as D:\ReazixBilling; on a Mac or Linux, a path starting with /.
2. Choose a folder outside the app's own folder.
3. For a USB disk, plug it in first. Settings says when a copy fails.
4. For a permission code such as EACCES, choose a folder in your own Documents or another drive.

See Keeping a copy somewhere else.

#Google Drive upload failed

You may see: "Google Drive not configured.", "Enter your Google OAuth Client ID first", "Drive auth failed — backup downloaded locally only", "Google Drive: Please reconnect in Settings" or "Google Drive upload failed: ...".

The file was still saved on this computer. Only the copy to Drive did not happen.

1. Check the internet.
2. In Settings, Google Drive, connect again (and fill in the Client ID if it is empty).
3. Save or export again.

#"Skipped damaged file" in the log

You may see a log line like: "Skipped damaged file data/bills/INV_0007.json (not valid JSON)", and that one invoice, client or product is missing from its list.

One saved file was damaged, by a power cut, a disk error or editing it by hand. The app skips it so everything else still opens.

1. Note the file name in the line (for example bills/INV_0007.json).
2. Open the data folder: Open Data Folder in the Control Panel.
3. Open backups, then the newest date folder, then the same subfolder (bills). Copy that file.
4. Paste it into the same subfolder of the data folder, replacing the damaged one, and reload the page.
5. No good copy there? Look in the ZIPs in Documents\Reazix Billing Backups, or move the damaged file to your Desktop (everything else keeps working) and send it to us.

Restoring a whole day from Settings, Backup Management also works, but it puts all your data back to that day. See Automatic daily backups.

#Mac

Messages macOS shows before the app starts.

#The Mac will not open the launcher

• "could not be executed because you do not have appropriate access privileges": open Terminal (Applications → Utilities), type chmod +x with a space after it, drag Reazix Billing - MAC into the Terminal window, press Return, and open the file again. Downloads from v1.10.82 do not need this. See the step-by-step example.
• "cannot be opened because Apple cannot check it for malicious software" or "unidentified developer": the app is not signed by Apple. Hold Control, click Reazix Billing - MAC, choose Open, then Open again. Only the first time. Or use System Settings → Privacy & Security → Open Anyway.
• "Node.js is not installed" or too old: see Node.js is too old.

Updating on a Mac: never drag a new download over the old folder; see Mac: other ways.

#Linux and NAS

Messages in the Terminal.

#"Permission denied" or "bash: not found"

You may see: "Permission denied" when starting ./Reazix Billing - LINUX.sh, or "bash: not found" on a NAS.

1. Start it through bash, which needs no permission change: cd ~/Reazix-Billing && bash "Reazix Billing - LINUX.sh".
2. No bash (Alpine, some NAS systems): install it, for example sudo apk add bash.
3. "Permission denied" while the app writes files: see The app is not allowed to write.

#The Linux update stopped

The update says ERROR: and, in most cases, "Nothing was changed." If it fails while applying, the old app files are put back.

• "Updating needs "unzip" (or python3)": run sudo apt install unzip (Alpine: apk add unzip) and update again.
• "Could not download the update": check the internet and try again.
• "could not be extracted (damaged download, or the disk is full)": free some space (see The disk is full) and try again.
• "Update Node.js as shown above": see Node.js is too old.
• "npm install failed.": check the internet and the free space, then run sh ~/Reazix-Billing/_system/update-unix.sh again.
• "This copy runs from a git checkout": update it with git pull && npm install && npm run build.

After "[OK] Update complete", restart the app (or its Docker container or service).

#Problem log and reporting a problem

The app keeps a list of recent problems on this computer: a save that failed, a screen that went wrong, the app server not answering. Open Help & Support in the sidebar and scroll to the Problem log card. Use it when something did not work and you want to know why, or when you want to send the details to get it fixed.

Private details are removed before anything is kept: GSTIN, PAN, phone numbers, email addresses, UPI IDs and bank account numbers. Nothing is sent anywhere unless you click Report.

No problems logged. Good. means nothing has gone wrong in this browser. The server log is empty. means the same for the server.

#Reporting a problem

1. In the Problem log, click Report next to the problem (or Report this problem on the panel that showed it).
2. Your email program opens a message to contact@reazix.com, already filled in with the version, your computer and the error details. Private details (GSTIN, PAN, phone, email, UPI ID, bank account) are removed first.
3. Add what you did just before it happened, check the text, and send it.

Reporting without the Problem log: the form asks for the version (bottom of the Dashboard, or Settings, App Updates), your computer, what you did and what you saw, and a screenshot (hide your GSTIN and bank details). If the app does not start, add what node -v and npm -v show in Command Prompt; see Using the Terminal.

Problems are fixed in the next update, and anything urgent, such as the app not opening, straight away. To ask for a new feature, email contact@reazix.com.

#Sending the details another way

No email program on this computer? Click Copy details (or Copy in the Problem log), paste it into an email to contact@reazix.com or a WhatsApp message, and add what you did just before it happened. Read it before sending; it is plain text.

#Questions

Things people ask that are not errors.

#Can I use it on my phone or another computer?

The app runs on the computer it is installed on, and only that computer can open it. It has no user accounts, so it is deliberately not shared over your network, where anyone connected could read your books. (The optional PIN lock locks the screen on this computer only.) To work on another computer, move your data there.

#Does it need the internet?

Only to install and to update. Invoices, reports, GST returns and even reading bills from photos all work offline. Google Drive upload uses the internet too.

#Is my data sent anywhere?

No. There is no account, no tracking and no server of ours. Your data stays in the app's folder unless you choose Google Drive, which copies files into your own Drive, or you send a problem report yourself. The full answer, with every address the app connects to, is in Is it safe?