When something's wrong with your app it can be hugely frustrating; so we want to make it as easy as we can for you to get to the bottom of these issues!
Step 1: check you're requesting what you think you're requesting
Often issues occur because your client code isn't doing what you think it's doing. The first step here is to determine exactly what's being sent over the network. If you're building a website you can easily use Google Chrome's Network Devtools to see exactly what's being sent and received.
- Open your website in Chrome
- Right click, and select 'Inspect'
- Select the 'Network' tab in the developer tools
- In the filter box, enter '/graphql' (or whatever path you have configured your API to use)
- Ensure that 'All' is selected to the right of the filter box
- Trigger your GraphQL request (either by reloading the page or by clicking the relevant element on the screen)
- Review the network requests that have arrived to ensure they're what you'd expect, that no variables are unexpectedly null, that the relevant access tokens are being set in the request headers, etc
Step 2: try your query in GraphiQL
It sometimes helps to try doing the same thing a different way, and this is
where GraphiQL comes in handy. Take the query you're running and execute it via
GraphiQL. Is it producing the same issue? Note that we currently do not support
setting headers in GraphiQL (although it is set to use
Credentials: same-origin which is helpful if you're using cookie-based sessions).
Step 3: increase PostGraphile's logging
Note that the errors are sent through to the GraphQL client (they're not
output on the server by default) so you'll need to reproduce this from your
client so you can see the output (or use a network inspector such as
WireShark if modifying the client is not an option). If you're using
PostGraphile as a library then you can use
handleErrors to output the error
details on the server side (and to manipulate them before they're returned to
You probably don't want this level of debugging on production as the results are sent to the client and it may leak implementation details you wish to keep private.
Use the following CLI options with PostGraphile:
--extended-errors hint,detail,errcode(other options available here)
or for the library:
extendedErrors: ['hint', 'detail', 'errcode'](other options available here)
extendedErrors: ['severity', 'code', 'detail', 'hint', 'positon', 'internalPosition', 'internalQuery', 'where', 'schema', 'table', 'column', 'dataType', 'constraint', 'file', 'line', 'routine']
- or use a custom
handleErrorsfunction to explore even more details about the errors (or to log them server side), note this overrides the above options. You might be interested in the
originalErrorproperty on the GraphQLErrors you're handed.
Step 4: viewing the generated SQL
Assuming that the error is coming from within the database, you can see what SQL statements PostGraphile is generating. To do so, restart PostGraphile, being sure to set the relevant DEBUG environmental variable first. For example:
# Bash (Linux, macOS, etc) export DEBUG="postgraphile:postgres" postgraphile -c postgres://... # Windows Console set DEBUG=postgraphile:postgres & postgraphile -c postgres://... # Windows PowerShell $env:DEBUG='postgraphile:postgres'; postgraphile -c postgres://...
Note that this works with PostGraphile CLI and also when using PostGraphile as
an express middleware (in which case replace the
postgraphile -c postgres://... command with your own server startup command).
To find details of any errors thrown whilst executing SQL, use:
# Bash (Linux, macOS, etc) export DEBUG="postgraphile:postgres,postgraphile:postgres:error" postgraphile -c postgres://... # or: export DEBUG="postgraphile:postgres*" postgraphile -c postgres://... # Windows Console set DEBUG=postgraphile:postgres,postgraphile:postgres:error & postgraphile -c postgres://... #or set DEBUG=postgraphile:postgres* & postgraphile -c postgres://... # Windows PowerShell $env:DEBUG = "postgraphile:postgres,postgraphile:postgres:error"; postgraphile -c postgres://... #or $env:DEBUG = "postgraphile:postgres*"; postgraphile -c postgres://...
We use a lot of DEBUG envvars for different parts of the system. Here's some of the ones you might care about:
postgraphile:cli- informs about plugins being loaded
postgraphile:graphql- prints out the full GraphQL query after validation and before execution
postgraphile:request- prints out statuses during the HTTP request life-cycle
postgraphile:postgres- prints out every SQL statement that's issued to the database (does not include placeholder values)
postgraphile:postgres:notice- outputs any notices generated whilst executing SQL statements (very useful for tracing functions/triggers)
postgraphile:postgres:error- outputs any errors generated whilst executing SQL statements
graphile-builder- desperately in need of renaming, this hook is extremely useful for understanding the order in which hooks execute, and how hook executions can nest - a must for people getting started with graphile-build plugins
graphile-build-pg- prints out various things, many of which should not occur. Also used to output errors from the update/delete mutations (where
nullis returned to GraphQL)
graphile-build-pg:warn- prints out warnings that occur during schema generation; these warnings might hint at field conflicts and similar issues
graphile-build-pg:sql- prints out some SQL statements, you probably want
graphql-parse-resolve-info- far more information than you could possibly need regarding how we process the resolveInfo / AST
To enable these DEBUG modes, join them with commas when setting a DEBUG envvar, then run PostGraphile or your Node.js server in the same terminal:
# Bash (Linux, macOS, etc) export DEBUG="postgraphile:graphql,postgraphile:request,postgraphile:postgres*" postgraphile -c postgres://... # Windows Console set DEBUG=postgraphile:graphql,postgraphile:request,postgraphile:postgres* & postgraphile -c postgres://... # Windows PowerShell $env:DEBUG = "postgraphile:graphql,postgraphile:request,postgraphile:postgres*"; postgraphile -c postgres://...
Advanced: getting your hands dirty
If you're a plugin author, you think you've discovered an issue in PostGraphile, or you just like seeing how things work, you can use the Chrome Debug tools to debug the node process - add breakpoints, break on exceptions, and step through code execution.
chrome://inspectin Google Chrome (we can't hyperlink it for security reasons).
- Select 'Open dedicated DevTools for Node', a new devtools window should open - don't close this!
- Run your server or PostGraphile via Node.js directly, in
# For globally installed PostGraphile: node --inspect `which postgraphile` -c postgres://... # or for locally installed PostGraphile: node --inspect node_modules/.bin/postgraphile -c postgres://... # or, if you have your own Node.js app in `server.js`: node --inspect server.js