Teams sometimes move JPQL out of inline createQuery calls into @NamedQuery declarations specifically for the fail-fast behaviour. What exactly does JPA/Hibernate check when the persistence unit boots, what does it not check, and how does that differ for @NamedNativeQuery?

## What 'startup validation' really means When a JPA persistence unit is built, Hibernate constructs an in-memory **mapping model**: every entity, its attributes, their types, associations and column mappings. Named JPQL queries are then processed against that model *before the application accepts traffic*. Concretely, for each named JPQL query the provider: 1. **Parses the string** into a syntax tree — an unbalanced parenthesis or a stray keyword fails here. 2. **Resolves the FROM clause** — `select b from Book b` requires an entity named `Book` in the model. Rename the entity (or its `@Entity(name=...)`) and this fails. 3. **Resolves every attribute path** — `b.author.lastName` requires `author` on `Book` and `lastName` on its target. This is the check that catches the classic refactor miss: someone renamed a field in the entity, the IDE updated all Java references, and the query strings silently rotted. 4. **Type-checks expressions and collects parameters** — comparing a string attribute to a number, or a function applied to the wrong type, is caught here. 5. **Generates SQL and caches the plan** under the query name. A failure aborts the bootstrap with the query name in the message. That is the whole value proposition versus inline `createQuery("...")`, whose identical typo waits silently for the first request that hits that code path — often a rarely exercised branch, often in production. ## The boundary: metadata, not schema The check is entirely **internal**. Hibernate compares the query against what your annotations/XML *claim* about the database. It does not connect and ask the database whether the table or column exists. Two distinct classes of drift therefore behave differently: - **Code drift** (entity/attribute renamed, association removed) → caught at startup. - **Schema drift** (column dropped in the database, type changed) → *not* caught by named-query validation. That is the job of `hibernate.hbm2ddl.auto=validate` / `jakarta.persistence.schema-generation`, a separate mechanism that does read the live catalog, and of migration tooling. Saying 'named queries validate my schema' in an interview is a precision error worth avoiding. ## Native named queries `@NamedNativeQuery(name = "Book.rawStats", query = "select ...")` holds vendor SQL. The provider has no grammar for every dialect, no knowledge of your functions, CTEs or hints, and no way to resolve identifiers that may be views or synonyms. So it stores the string, stores any declared result-set mapping, and defers everything to execution. A typo surfaces as the driver's error wrapped in a `SQLGrammarException` (or a `PersistenceException`) on first call. There is a partial exception: the *result mapping* attached to a named native query (a `@SqlResultSetMapping` name, or a `resultClass`) refers to mapping metadata, so a mapping name that does not exist is a bootstrap error. The SQL body itself is not. Practical consequence: the fail-fast argument that justifies named JPQL does **not** transfer to native SQL. If you keep native queries, you buy back the confidence with integration tests that execute each one against a real database instance — ideally the same engine and version as production, since the failure mode is dialect-specific. ## Controlling and using the check Hibernate exposes a switch that turns the startup check off (historically `hibernate.query.startup_check`). Disabling it is almost always the wrong instinct — it converts a loud, immediate failure into a latent one. The legitimate reasons are narrow: shaving bootstrap time in a huge legacy unit, or tolerating a query that uses a dialect feature the parser mishandles (in which case the honest fix is to move that query to native SQL and test it). A useful way to exploit the behaviour deliberately: because validation covers *all* named queries at once, promoting the important queries in a service to named queries turns application startup into a compile-time-ish contract check over the query surface. In a CI pipeline that boots the context, a mapping refactor that misses a query string fails the build rather than a customer request. Inline strings can get some of this from metamodel-based Criteria queries, which are checked by the Java compiler instead — a different route to the same guarantee. ## What still slips through Even for JPQL, validation is structural. It will not tell you that the query does a Cartesian product, that it triggers N+1 selects, that it returns the wrong rows, or that it will be slow. Those need tests and query-plan inspection. Startup validation buys you *'this query is expressible against the current mappings'* — necessary, not sufficient.