A developer-first portal for installing, configuring, rebranding, and shipping the codebase.
Documentation /Help
Troubleshooting Guide
Diagnostic and resolution procedures for issues commonly encountered when installing, configuring, and validating the FIDE Request Quote & Hide Price Source Code Edition.
12 min read
1. Purpose and Scope
This guide provides diagnostic and resolution procedures for issues commonly encountered when installing, configuring, and validating the FIDE Request Quote & Hide Price Source Code Edition.
1.1 In scope
Local environment preparation and dependency installation.
Environment variable and configuration file setup.
Database provisioning and Prisma bootstrap.
Shopify Partner app linking, tunnelling, and authentication.
Post-installation verification of the running application.
1.2 Out of scope
Custom code modifications made by the buyer after delivery.
Third-party hosting, DNS, and infrastructure faults.
Shopify platform outages and upstream API incidents.
Theme conflicts introduced by unrelated apps or custom theme code.
1.3 Intended audience
Developers and technical implementers responsible for installing the source code in a local development environment and preparing it for deployment. Working familiarity with Node.js, npm, Git, and the Shopify CLI is assumed.
2. Prerequisites
Confirm every item below before beginning installation. A significant proportion of reported issues trace back to an unmet prerequisite rather than a defect in the source code.
Requirement
Notes
Verification command
Node.js
Use the version stated in the Installation Guide.
node -v
npm
Bundled with Node.js.
npm -v
Git
Required for version control and delivery handling.
git --version
Shopify CLI
Used for app linking and the development server.
shopify version
Shopify Partner account
Required to create and link the Partner app.
Partner Dashboard access
Shopify development store
Target store for installation and testing.
Store admin access
PostgreSQL database
A reachable instance with a valid connection string.
DATABASE_URL
Environment variables
All values in .env populated before first start.
cat .env
Project path
Must not contain spaces in any directory name.
Inspect the absolute path
3. How to Use This Guide
Each issue is recorded under a unique reference so it can be cited precisely in support requests. Quote the reference (for example, DB-001) when contacting the development team.
Prefix
Category
Covers
ENV
Environment and dependencies
Node, npm, shell behaviour, package installation
CFG
Configuration files
.env values and Shopify TOML configuration
DB
Database and Prisma
Connection, migration, and client generation
SHP
Shopify platform
App linking, tunnelling, and authentication
Severity indicates the effect on installation progress:
Severity
Definition
High
Installation cannot proceed until the issue is resolved.
Medium
Installation is blocked at a specific step but a defined workaround exists.
Low
Cosmetic or informational; installation continues unaffected.
4. Quick Diagnostic Index
Locate the observed symptom in the left column and go to the corresponding reference in Section 5.
Observed symptom
Reference
Category
Warnings printed during package installation
ENV-001
Environment
Ampersand chaining rejected by the shell
ENV-002
Environment
Application will not start; no environment file present
CFG-001
Configuration
Database connection string not configured
CFG-002
Configuration
Startup fails due to a missing staging configuration file
CFG-003
Configuration
Startup fails due to a missing app proxy section
CFG-004
Configuration
Prisma migration or client generation fails
DB-001
Database
The setup script is not available
DB-002
Database
The Prisma command is not recognised
DB-003
Database
Partner app cannot be linked
SHP-001
Shopify
Tunnel address is unreachable
SHP-002
Shopify
Repeated authentication prompts
SHP-003
Shopify
5. Troubleshooting Reference
5.1 Environment and dependencies
ENV-001Warnings during package installationLOW
Symptom
Warning messages are printed to the terminal while dependencies are being installed.
Probable cause
Advisory notices emitted by third-party packages, typically relating to deprecated transitive dependencies.
Resolution
Continue with the installation. These warnings are informational and do not prevent the packages from being installed correctly.
Verification
Installation completes and the node_modules directory is created.
Notes
Report the output only if installation terminates with an error rather than a warning.
ENV-002Command chaining rejected in PowerShellLOW
Symptom
A command that chains two operations with an ampersand pair is rejected by the shell.
Probable cause
Older versions of Windows PowerShell do not support the ampersand chaining operator used in the documented commands.
Resolution
Run each command separately, in the documented order.
npx prisma generatenpx prisma migrate deploy
Verification
Each command completes independently without a syntax error.
Notes
Alternatively, run the commands in Command Prompt, Git Bash, or Windows Terminal.
5.2 Configuration
CFG-001Environment file missingHIGH
Symptom
The application does not start and reports that required configuration is unavailable.
Probable cause
The environment file has not been created from the supplied template.
Resolution
Copy the supplied example file and populate every required value before starting the application:
cp .env.example .env
Refer to the Installation Guide for the meaning of each variable.
Verification
The .env file exists in the project root and no placeholder values remain.
Notes
Never commit the populated .env file to version control.
CFG-002Database connection string not configuredHIGH
Symptom
The application cannot establish a connection to the database.
Probable cause
The DATABASE_URL variable is absent, empty, or contains a placeholder value.
Resolution
Set a valid PostgreSQL connection string in the .env file:
Confirm the host is reachable from the machine running the application and that the credentials are correct.
Verification
Prisma commands connect to the database without a connection error.
Notes
Managed database providers may require SSL parameters to be appended to the connection string.
CFG-003Staging configuration file missingHIGH
Symptom
Startup fails because an expected Shopify application configuration file is not present.
Probable cause
The staging configuration file was not created or was excluded during transfer.
Resolution
Verify that all required configuration files are present in the project root as listed in the Installation Guide, and recreate any that are missing.
Verification
All required configuration files are present and the application proceeds past the startup check.
CFG-004App proxy section missingHIGH
Symptom
The application fails to start, or storefront requests are not routed correctly.
Probable cause
The app proxy section is absent from the Shopify application configuration file.
Resolution
Add the app proxy section to the Shopify application configuration file using the values given in the Installation Guide, then restart the development server.
Verification
The application starts and storefront proxy requests resolve successfully.
Notes
The proxy prefix and subpath must match the values registered for the app in the Partner Dashboard.
5.3 Database and Prisma
DB-001Prisma bootstrap failsHIGH
Symptom
Migration or client generation terminates with an error before completing.
Probable cause
The absolute path to the project directory contains one or more spaces.
Resolution
Move the project to a path that contains no spaces in any directory name, then run the commands again:
npx prisma generatenpx prisma migrate deploy
Verification
Both commands complete successfully and the Prisma client is generated.
Notes
Paths under user profile directories often contain spaces. A short root-level path is recommended.
DB-002Setup script unavailableMEDIUM
Symptom
The setup script cannot be executed.
Probable cause
The script is not defined in the current package configuration.
Resolution
Run the underlying commands directly, in this order:
npx prisma generatenpx prisma migrate deploy
Verification
The database schema is applied and the Prisma client is generated.
DB-003Prisma command not recognisedMEDIUM
Symptom
The shell reports that the Prisma command cannot be found.
Probable cause
The Prisma CLI is not installed globally and is therefore not on the system path.
Resolution
Invoke the locally installed CLI through npx rather than calling it directly:
npx prisma generatenpx prisma migrate deploy
Verification
The commands execute and report the Prisma version in use.
Notes
A global installation is not required and is not recommended, as it can diverge from the project version.
5.4 Shopify platform
SHP-001Partner app cannot be linkedHIGH
Symptom
The application cannot be linked to a Shopify Partner app.
Probable cause
The session is authenticated against the wrong account, or the wrong Partner organisation is selected.
Resolution
Sign in with the correct Partner account, confirm the intended organisation is selected, and run the link command again:
npm run config:link
Verification
The link completes and the configuration file is populated with the correct application identifier.
Notes
Where an account has access to several organisations, confirm the selection carefully at the prompt.
SHP-002Tunnel address unreachableMEDIUM
Symptom
The generated tunnel address does not load in the browser.
Probable cause
The tunnel session has expired or was terminated with the development server.
Resolution
Restart the development server to establish a new tunnel:
npm run dev
Use the newly generated address; the previous one is no longer valid.
Verification
The new address loads the application and the embedded admin renders.
Notes
Tunnel addresses are temporary and change on each restart. Do not treat them as a fixed URL.
SHP-003Repeated authentication promptsMEDIUM
Symptom
The user is returned to the login prompt repeatedly and the session does not persist.
Probable cause
The authentication session has expired, or it was established against a tunnel address that is no longer current.
Resolution
Stop the development server, start it again, and complete authentication once more:
npm run dev
If the loop persists, clear the browser session for the store domain and repeat.
Verification
Authentication completes once and the session persists across page navigation.
Notes
This condition frequently accompanies SHP-002. Resolve the tunnel first.
6. Post-Installation Verification
Complete every check below before treating the installation as fully verified. Record the outcome against each item. Any failed check should be investigated using Section 5 or raised with the development team.
Ref
Check
Expected result
Outcome
V-01
Dashboard
The dashboard loads without error.
V-02
Quote List
Existing quote requests are listed.
V-03
Quote Settings
Settings load and can be saved.
V-04
Settings page
The settings page renders in full.
V-05
Quote Form Builder
The builder loads and fields can be edited.
V-06
Theme App Extension
The extension appears and functions in the storefront.
V-07
Database connection
Records are read and written successfully.
V-08
Email templates
Templates render and test messages are dispatched.
V-09
Browser console
No errors are reported in the console.
V-10
Server logs
No unhandled exceptions are recorded at startup.
7. QA Observations
During Fresh Installation QA validation, minor gaps were identified in the installation documentation and project configuration. The developer reviewed the installation jointly with QA and confirmed that the Installation Guide would be updated to include the missing steps. After the required configuration updates were applied, the application started successfully.
The QA validation confirmed that the installation could be completed after the identified configuration and documentation gaps were addressed. Functional verification should be recorded separately against the Post-Installation Verification checklist in Section 6.
NOTE
No defects in the application source code were identified during this validation cycle. All observations related to documentation completeness and local environment configuration.
8. Escalation and Support
8.1 Before raising a request
Complete the following self-checks. They resolve the majority of reported issues and, where they do not, they produce the information required to diagnose the problem.
Confirm every prerequisite in Section 2 is satisfied.
Re-read the relevant section of the Installation Guide in full.
Verify that all environment variables are present and correctly valued.
Review the terminal output and server logs for the first error, not the last.
Search the Quick Diagnostic Index in Section 4 for a matching symptom.
8.2 Information to include
Requests that omit this information cannot be triaged and will be returned for clarification.
Item
Detail required
Issue reference
The reference from Section 5, where one applies.
Product version
The version of the source code in use.
Operating system and shell
For example, Windows 11 with PowerShell.
Runtime versions
Output of node -v and npm -v.
Step reached
The exact step in the Installation Guide at which the issue occurred.
Terminal output
The complete error output as text, not as a partial excerpt.
Screenshots
Screens showing the error state, where it is visible in the interface.
Actions already taken
The resolutions already attempted and their outcome.
8.3 Contact
Support channel
Detail
Support channel
[Support email address]
Hours of operation
[Business hours and time zone]
Target first response
[Response target]
Support entitlement
As defined in the Commercial License Agreement.
Scope of support
Support covers the source code as delivered. Issues arising from buyer modifications, third-party hosting, or unrelated theme and app conflicts fall outside the scope of support, although guidance may be offered at the discretion of the development team.
Appendix A — Command Reference
Command
Purpose
npm install
Install project dependencies.
npm run config:link
Link the project to a Shopify Partner app.
npm run dev
Start the development server and establish a tunnel.
npx prisma generate
Generate the Prisma client from the schema.
npx prisma migrate deploy
Apply pending migrations to the database.
cp .env.example .env
Create the environment file from the supplied template.
