Sails.js Web Framework

Common errors

• TypeError: Cannot set headers after they are sent to the client

  cause Attempting to send multiple HTTP responses for a single request, often due to improper `res.send()` or `res.json()` usage after another response has already been sent, or due to unhandled errors that implicitly send a default response.
  fix Ensure that each request handler (action, policy, middleware) sends only one response. Use `return` before `res.send()`, `res.json()`, `res.serverError()`, etc., to prevent further code execution after a response has been dispatched. Implement robust error handling.

• Error: An app failed to lift. (Usually means a hook threw an error)

  cause A common startup error in Sails, indicating an issue during the application bootstrap or hook initialization phase. This can be due to misconfigured database connections, invalid model definitions, syntax errors in config files, or unhandled exceptions in bootstrap logic.
  fix Check server logs for more specific error messages from individual hooks, models, or configurations. Verify database connection settings in `config/datastores.js` and model definitions for correctness. Review the `config/bootstrap.js` file for any problematic logic. Incrementally comment out hooks or custom logic to isolate the problematic component.

• E_UNIQUE: A uniqueness constraint was violated

  cause Attempting to create or update a record with a value for an attribute that has been defined with a `unique: true` constraint, and that value already exists in the database.
  fix Before creating or updating, perform a check to see if a record with the unique value already exists. Handle the `E_UNIQUE` error specifically in `try/catch` blocks or promise `.catch()` handlers, providing appropriate feedback to the user or logic to resolve the conflict.

Warnings

• breaking Upgrading to Sails v1.0 from any v0.x version involved significant breaking changes, including changes to configuration (especially datastores), model definitions (e.g., `autoPK` removed), and the results of `.create()`, `.update()`, and `.destroy()` methods. Many core hooks became direct dependencies.
  Fix: Refer to the official Sails.js upgrade guides (e.g., 'Upgrading to Sails v1.0') and consider using the `sails upgrade` tool. Migrate your application incrementally, addressing database configuration, model attribute definitions, and asynchronous API usage.
• gotcha When programmatically lifting Sails applications, such as for testing, environment variables like `.sailsrc` settings are not automatically applied. Additionally, running multiple Sails app instances in the same process with globals enabled can lead to collisions.
  Fix: Pass configuration overrides directly to the `.lift()` or `.load()` methods. For `.sailsrc` specific configurations, use `require('sails/accessible/rc')('sails')` and pass them in. Disable unnecessary hooks and globals (`globals: false`) when running multiple instances or in test environments.
• breaking Sails v1.0+ fully embraces `async/await` for asynchronous operations. While traditional `.exec()` with callbacks is still supported, mixing styles or neglecting error handling with promises (`.then().catch()`) can lead to unhandled rejections and instability.
  Fix: Standardize on `async/await` for all asynchronous model methods and other operations. Ensure proper `try/catch` blocks are used. If using `.then()` chains, always include a `.catch()` to prevent unhandled promise rejections.
• gotcha From v1.3.1, an update to the `machine-as-action` dependency included a reminder about escaping strings with dynamic data when injected into views or responses, indicating a potential XSS vulnerability if not handled correctly.
  Fix: Always sanitize and escape user-provided or dynamic data before rendering it in views or sending it in HTTP responses to prevent Cross-Site Scripting (XSS) attacks. Utilize templating engine auto-escaping features or specific sanitization libraries.
• deprecated The `sails.services` object, while still accessible, has been superseded by 'helpers' since Sails v1.0. The new 'Actions2' syntax for controllers also streamlines definition and validation.
  Fix: For new logic, use 'helpers' instead of 'services'. Adopt the 'Actions2' syntax for new controller actions to benefit from automatic parameter validation and clear exit definitions.

Install

• npm install sails npm
• yarn add sails yarn
• pnpm add sails pnpm

Imports

• Sails (for programmatic use)
  wrong:

  import Sails from 'sails';

  correct:

  const Sails = require('sails').constructor;

  For programmatic interaction (e.g., in tests or scripts), instantiate `Sails` using its constructor to avoid singleton issues and to manage multiple app instances. Direct `import` syntax is not natively supported for the core framework in Node.js applications unless a transpiler like Babel is used.
• sails (global instance)
  wrong:

  import sails from 'sails';

  correct:

  const sails = require('sails');

  Within a running Sails application (e.g., in controllers, services, or models), a singleton `sails` instance is automatically available, often globally. `require('sails')` will return this singleton instance. Using `import` directly for `sails` in application code might require Babel or other transpilation for full ESM support.
• Model access (e.g., User)
  wrong:

  import { User } from '../api/models/User';

  correct:

  const User = sails.models.user; // Or simply `User` if globals are enabled

  In a Sails application, models are typically accessed via the global `sails.models` object (e.g., `sails.models.mything`) or, by default, directly as global variables (e.g., `Mything`) if `sails.config.globals.models` is `true`. Direct file imports for models are generally not the idiomatic Sails way.

Quickstart

This quickstart demonstrates how to set up a new Sails.js project using its CLI, generate basic model and controller files, lift the application, and then programmatically interact with the lifted app's models from an external script.

```bash
# Install Sails CLI globally
npm install sails -g

# Create a new Sails project
sails new my-sails-app --no-template
cd my-sails-app

# Generate a simple User model
sails generate model User name:string email:string

# Generate a UserController
sails generate controller User --actions 'find,create'

# Lift the Sails application (start the server)
sails lift

# --- Example of programmatic interaction (after lifting) ---
# In a separate script, e.g., `test.js`:
# const Sails = require('sails').constructor;
# const sailsApp = new Sails();
#
# sailsApp.lift({ log: { level: 'warn' } }, async (err) => {
#   if (err) {
#     console.error('Error lifting Sails app:', err);
#     return;
#   }
#   console.log('Sails app lifted successfully!');
#
#   try {
#     // Access a model and create a record
#     const User = sailsApp.models.user; // Access the model instance
#     const newUser = await User.create({
#       name: 'Alice Smith',
#       email: 'alice@example.com'
#     }).fetch();
#     console.log('Created user:', newUser);
#
#     // Find all users
#     const users = await User.find();
#     console.log('All users:', users);
#   } catch (queryErr) {
#     console.error('Database query error:', queryErr);
#   } finally {
#     sailsApp.lower((lowerErr) => {
#       if (lowerErr) console.error('Error lowering Sails app:', lowerErr);
#       else console.log('Sails app lowered.');
#     });
#   }
# });
```