Deployment Related Troubleshooting

Here’s an easy-to-follow guide to some common hurdles you may face while deploying your apps on Emergent.

The list is not exhaustive, and you may face issues that are not listed here. For the general format to follow when troubleshooting, do refer to the other articles in the Troubleshooting tab.

Overview

Deployment is how your app goes from a live preview URL that is only active for 30 minutes at a time to an always accessible, permanent live link that you can share with friends, colleagues, clients and the world at large.

Deployment is essentially moving the code from one “workspace” to another. Here are some common issues you may face, and how to solve them:

Issue 1: Missing API Configurations

Imagine you built an app that needs to:

• Send emails
• Process payments with Stripe
• Use AI from OpenAI
• Connect to a database

Each of these services needs a “key” (like a password) to work. During development, these keys might be stored locally on your computer. But when deploying, you need to give those keys to the deployment system.

You’ll know this is the problem if your app deploys but you see errors such as features that stop working, error codes like “undefined” or “missing API key”

Here’s what you can ask the agent:

The app is missing the following functionalities:
1. [Feature 1] is not working right. It should do [ABC] but currently stops at [A]
2. [Feature 2] fails with [Error Code XYZ] in the console

Are there any missing API keys or Environment Variables that need to be fixed?

To avoid this situation, we advise you to ask the agent if the project is missing any external configurations before attempting to deploy your app. Here’s a quick prompt you can use:

Before I deploy, can you check if there are any API keys or 
environment variables I need to configure? 
Please list everything I'll need to provide.

Issue 2: Database Connection Errors

Following the same example from the last issue, you may notice that the data you filled in during the preview stage does not carry over in the deployed app.

The reason can be traced back to one key fact: The preview environment and the deployed environment on Emergent are two separate “spaces” - different environment, different databases. When you deploy an app, the settings from one space is summarised and moved to the final deployed space.

You’ll know the issue is database related if you see:

• App starts but database related features are not loading (incomplete data points, features that save or load data don’t work)
• Errors mentioning “MongoDB” or “Invalid Database Connection”
• User logins, posting, or loading of items fail
• Error messages about “connection timeouts” or “authentication failed”

In this situation, it is vital that we avoid prompting the agent with vague prompts that do not explain the gaps in functionality clearly. Here’s the kind of prompts that will actually help:

Scenario 1: Database won’t connect

My app deployed but the database isn't connecting. I'm seeing these errors:
[Paste error message]

Features that aren't working:
- [e.g., "User login"]
- [e.g., "Saving posts"]
- [e.g., "Loading data"]

Can you:
1. Check the database connection configuration
2. Make sure the database is set up correctly for deployment
3. Fix any connection issues

Scenario 2: Features worked locally but not after deployment

Everything worked fine in development, but after deployment, anything involving saving or loading data fails.

Specifically:
- [Describe what's not working]

I think the database connection isn't set up right for deployment. Can you diagnose and fix this?

To avoid this situation, we advise you to ask the agent if the project has any database connection errors before attempting to deploy your app. Here’s a quick prompt you can use:

Please make sure the database connection will work in deployment.
Add initialization code if needed, and make sure all required 
collections/stables are created automatically.

Issue 3: Missing Libraries or Dependancy Issues

Your app is built using various libraries or packages. Each of these libraries are called a “dependancy”.

Sometimes when deploying:

• The wrong versions of such libraries are used
• The library that is used in the preview environment is different from the library used in the deployed environment
• A library is not installed or incorrectly installed

This is an avoidable error by either asking the agent to verify that such issues do not exist, or by running a Pre-Deployment Health Check.

Here’s how you know your error falls into this category:

• Deployment failed during the ‘Building’ phase.
• Errors saying ‘Module Not Found’
• Errors mentioning specific library names

Here are some examples to better illustrate the kind of prompts that help with these issues:

Scenario 1: Deployment fails with “module not found”

My deployment is failing with this error:
[Paste the error message - especially ones mentioning "module not found" or "cannot find"]

Can you fix the missing dependencies and make sure everything is installed correctly?

Scenario 2: App crashes after building

The app builds successfully but then crashes when starting. The error says:
[Paste error message]

I think some dependencies are missing or not configured correctly. Can you:
1. Check what's missing
2. Install/fix the dependencies
3. Make sure the app will start correctly in deployment

Scenario 3: Added new features with new libraries

I just asked you to add [feature name] which uses [library name - e.g., "Stripe" or "Framer Motion"].

Before I deploy, can you make sure:
1. All new dependencies are properly installed
2. They're added to the requirements/package files
3. Everything will work in deployment

Scenario 4: General dependency check

Before I deploy, can you:
1. Check that all dependencies are properly listed
2. Make sure there are no missing packages
3. Verify everything is installed correctly
4. Fix any version conflicts

I want to make sure deployment won't fail due to missing dependencies.

As always, here is a simple prompt you should share with the agent before deploying the app, to prevent such errors from occuring:

Can you make sure all the dependencies for this new feature are properly installed and will work in deployment?