Parse Server

Common errors

• MongoNetworkError: failed to connect to server [localhost:27017] on first connect

  cause The MongoDB database server is not running or is not accessible at the specified URI.
  fix Ensure MongoDB is running and accessible from the Parse Server host. Verify the `databaseURI` in your Parse Server configuration (e.g., `mongodb://localhost:27017/yourdbname`).

• Parse initialization failed: Invalid application id.

  cause The `appId` configured in Parse Server does not match the `appId` used by your Parse SDK client.
  fix Double-check that the `appId` value in your Parse Server configuration (e.g., `new ParseServer({ appId: 'YOUR_APP_ID' })`) is identical to the one your Parse SDK client uses to initialize.

• Error: Could not find Parse.Cloud.define for function 'myCloudFunction'

  cause The specified Cloud Code function is not defined, or the Cloud Code file was not loaded correctly by Parse Server.
  fix Verify that your Cloud Code file (e.g., `cloud/main.js`) contains `Parse.Cloud.define('myCloudFunction', ...)` and that the `cloud` option in your Parse Server configuration points to the correct path.

• TypeError: Cannot read properties of undefined (reading 'app')

  cause This usually indicates that `new ParseServer(...)` was not properly instantiated or its `app` property is being accessed before it's ready.
  fix Ensure `parseServerApi.app` is accessed only after `new ParseServer` has completed its initialization. Confirm all required configuration options (e.g., `appId`, `masterKey`, `databaseURI`) are provided.

Warnings

• breaking Multiple security vulnerabilities (GHSA-g4v2-qx3q-4p64, etc.) were addressed in versions 9.8.0 and subsequent alphas that fixed endpoints bypassing `_Session` and `_User` `protectedFields`. This may change behavior for applications that inadvertently relied on these bypasses.
  Fix: Upgrade to `parse-server@9.8.0` or higher immediately. Review and adapt any client-side or cloud code logic that might have been exploiting previous unprotected field access.
• breaking Node.js engine requirements are very specific and frequently updated. Version 9.8.0 requires Node.js `^20.19.0`, `^22.12.0`, or `^24.11.0`. Running on unsupported Node.js versions may lead to unexpected behavior or failures.
  Fix: Ensure your Node.js environment strictly adheres to the `engines.node` specification in `package.json`. Use a tool like `nvm` to manage and switch Node.js versions as needed.
• gotcha The `masterKey` provides unrestricted access and bypasses all ACLs/CLPs. It should be used with extreme caution and never exposed to client-side code. Misuse can lead to severe security breaches.
  Fix: Only use the `masterKey` in secure server-side environments (e.g., Cloud Code, administrative scripts). Never include it in frontend applications or expose it via APIs. Implement granular ACLs/CLPs for client operations.
• gotcha Cloud Code is JavaScript/TypeScript code that runs on the Parse Server. Changes made to Cloud Code are not automatically reloaded in production environments without restarting the Parse Server instance. This can lead to stale logic.
  Fix: Implement a deployment strategy that restarts the Parse Server process after Cloud Code changes. For development, consider using `nodemon` or similar tools for automatic restarts on file changes.
• deprecated Older authentication methods or social login providers might become deprecated or require updated configurations as third-party APIs evolve. Always check the Parse Server documentation for the latest integration guides.
  Fix: Regularly review your authentication provider configurations (e.g., Facebook, Google, Apple) and update them according to the latest Parse Server and provider-specific documentation. Keep your `parse-server` package updated.

Install

• npm install parse-server npm
• yarn add parse-server yarn
• pnpm add parse-server pnpm

Imports

• ParseServer
  wrong:

  const ParseServer = require('parse-server').ParseServer;

  correct:

  import { ParseServer } from 'parse-server';

  Preferred ESM import. While CJS is supported, ESM is standard for modern Node.js applications and recommended for TypeScript.
• ParseGraphQLServer
  wrong:

  import { ParseGraphQLServer } from 'parse-server';

  correct:

  import { ParseGraphQLServer } from 'parse-server/lib/GraphQL/ParseGraphQLServer';

  The GraphQL server is typically imported from a specific internal path, not directly from the main package export.
• Config
  wrong:

  import Config from 'parse-server/lib/Config';

  correct:

  import { Config } from 'parse-server';

  Configuration utility class, typically imported directly from the main package.

Quickstart

Sets up a basic Parse Server instance with Express.js, connecting to a MongoDB database, enabling Cloud Code, Live Queries, and a basic email adapter for user verification.

import express from 'express';
import { ParseServer } from 'parse-server';
import path from 'path';

const app = express();
const port = 1337; // Port for your Express app

// Database connection string (e.g., MongoDB, PostgreSQL)
const databaseUri = process.env.DATABASE_URI ?? 'mongodb://localhost:27017/dev';

// Initialize Parse Server
const parseServerApi = new ParseServer({
  databaseURI: databaseUri,
  cloud: path.join(__dirname, 'cloud/main.js'), // Path to your Cloud Code
  appId: process.env.APP_ID ?? 'myAppId',
  masterKey: process.env.MASTER_KEY ?? 'myMasterKey',
  serverURL: process.env.SERVER_URL ?? `http://localhost:${port}/parse`, // Your Parse Server URL
  liveQuery: {
    classNames: ['Post', 'Comment'], // Classes to enable for Live Queries
  },
  // Ensure publicServerURL matches the client-facing URL for file uploads, etc.
  publicServerURL: process.env.PUBLIC_SERVER_URL ?? `http://localhost:${port}/parse`,
  verifyUserEmails: true,
  emailAdapter: {
    module: 'parse-server-simple-mailgun-adapter',
    options: {
      fromAddress: 'no-reply@example.com',
      domain: process.env.MAILGUN_DOMAIN ?? 'example.com',
      apiKey: process.env.MAILGUN_API_KEY ?? 'YOUR_MAILGUN_API_KEY',
    },
  },
});

// Mount the Parse API on the /parse URL prefix
app.use('/parse', parseServerApi.app);

// Basic Express route
app.get('/', (req, res) => {
  res.status(200).send('Parse Server is running.');
});

// Start the Express server
app.listen(port, function() {
  console.log(`Parse Server running on http://localhost:${port}`);
  console.log('Make sure your database (e.g., MongoDB) is also running!');
});

// Example Cloud Code (./cloud/main.js):
/*
Parse.Cloud.define('hello', (request) => {
  return 'Hello from Cloud Code!';
});
*/