Troubleshooting

Troubleshooting

This page covers common problems you may encounter when installing, configuring, or running FCDex.

Dependency installation fails

Run the following command from the project directory:

bun install

Check that Bun is installed correctly and that your terminal is open in the FCDex repository.

If installation still fails, review the error message and check your network connection.

Configuration file is missing

Generate your local configuration with:

bun run setup

If config.ts already exists, inspect it before making changes. Back up your configuration before attempting any manual fixes.

Discord login fails

Check the following:

• Your Discord bot token is correct.
• The token has not been reset or revoked.
• Required configuration values are present.
• Your bot application exists in the Discord Developer Portal.

Never post your bot token in a GitHub issue or support message.

Bot commands do not work

If the bot starts but commands do not respond, check:

• Whether the commands have been registered with Discord.
• Whether the bot has the required permissions.
• Whether the relevant package is enabled.
• Whether the command implementation exists in your version.
• Whether the terminal reports registration or execution errors.

Database connection fails

Verify that:

• PostgreSQL is running and reachable.
• Your database connection settings are correct.
• The database exists.
• The database account has the required permissions.
• Network and firewall settings permit the connection.

Never share an unredacted database connection string when asking for help.

Prisma client errors

Generate the Prisma client:

bun run db:generate

If the error persists, inspect the Prisma schema, installed dependencies, and complete error message.

Generating the client does not create or update database tables.

Build fails

Run:

bun run build

Read the TypeScript compiler output and resolve the reported errors.

Check that imported files exist and that their paths, exports, and types match the code using them.

Compiled application will not start

The current start script expects the compiled file at dist/index.js.

Build the project first:

bun run build

Then start it:

bun run start

If compilation fails, fix the build errors before starting the application.

Database migration concerns

Never run unreviewed migrations against a production database or an existing BallsDex database.

Before changing a database:

1. Create a backup.
2. Verify that the backup can be restored.
3. Review the Prisma schema and migration history.
4. Test the changes on a separate database.

FCDex's dedicated BallsDex migration tooling is planned for a later development phase.

Still need help?

You can:

• Join the FCDex Discord community
• Open a GitHub issue

When reporting a problem, include the relevant error message, your operating system, and the steps needed to reproduce the issue.

Before sharing logs, remove tokens, passwords, database connection strings, and private user data.

Related pages

• Installation
• Configuration
• Database Setup
• Running FCDex
• Package System