Across 24 chapters, a few pitfalls have already shown up individually as warning callouts. This chapter bundles them into a systematic troubleshooting overview, organized by symptom rather than by cause - so it works as a reference when something actually breaks.

Symptom: every GraphQL request fails, even unrelated ones

If every GraphQL request fails - even for core queries that have nothing to do with your own module - it's almost always a syntax/parsing error in some schema.graphqls (chapter 4). The entire schema gets parsed as one unit; a single broken module takes every other module down with it.

• A missing or extra curly/square bracket from one of the most recent changes.
• A referenced type (e.g. SearchResultPageInfo, FilterTypeInput) doesn't exist because the module dependency in module.xml (chapter 4) is missing or misspelled.
• A typo in a type name in extend type (chapter 8) - CategoryInterface instead of Category is the classic case.

Symptom: "Cannot query field" even though the code looks correct

Only once a fresh cache clean fails to fix the problem is it worth looking for actual typos in the field name itself - capitalization matters, GraphQL is case-sensitive.

Symptom: a field always returns null, even though data exists

Three possible causes, in the order that's fastest to rule out:

1. The @resolver directive is missing or points to a misspelled class - the default resolver from chapter 2 then kicks in and looks for a same-named array key that doesn't exist for the more complex field.
2. The parent resolver doesn't supply the expected key (e.g. model) in the $value array - checking with var_dump($value) or xdebug (chapter 10) clarifies this quickly.
3. The field resolver itself throws a silently swallowed exception - a look at var/log/exception.log (bin/log exception.log) reveals the actual error in this case.

Symptom: "Internal server error" with no details at all

This generic message appears for any exception that is not one of the four GraphQL exceptions from chapter 19 - in production mode, the actual cause is deliberately masked. For local development, switching to developer mode helps:

bin/magento deploy:mode:show
bin/magento deploy:mode:set developer
bin/log exception.log

In developer mode, the GraphQL response includes a full stack trace in the debugMessage field of the error response - in production mode, this field stays empty, and the full information can only be found in the server log.

Symptom: a mutation fails with a misleading error

A classic with input types (chapters 6, 16): if a required field in an input type is forgotten, GraphQL reports a validation error directly against the schema before any resolver even runs - the message names the missing field, but beginners often look for the bug in the PHP resolver first, even though it was never called in this case.

With this troubleshooting overview, the circle closes back to chapter 1 - chapter 26, the series' final chapter, wraps up every important pattern into a compact cheat sheet.