JetEngine Query Builder Mistakes: 5 Common Problems and Fixes

When a JetEngine Query Builder setup returns nothing or the wrong items, the cause is almost always one of five settings. Check the form field's dynamic options source, a Query ID that doesn't match in all three places, ordering by a meta field without a named meta clause, a fixed Posts query on an archive template instead of Current WP Query, and REST endpoint arguments that were never mapped with the Query Variable tag. If results look stale or random, first switch off Cache Query in the query's General Settings and retest.

Below you get the symptom for each mistake, the exact setting to change, and what you should see once it works.

• Quick diagnosis: symptom to cause
• 1. Form dropdown fed by a query is empty
• 2. Filters don't reach the listing (Query ID)
• 3. Sorting by a meta field without a named clause
• 4. Archive pages built on a fixed Posts query
• 5. REST endpoints with hard-coded limits
• Troubleshooting checklist

Quick diagnosis: symptom to cause

1. Form dropdown fed by a query is empty

You can fill a JetFormBuilder Select, Radio or Checkbox field with items from a Query Builder query. Selecting the field alone isn't enough. You also have to tell the field which query to run and which property of each item to save. You may see advice to type a pipe-separated string such as 15|ID|post_title. That string (query ID|value|label) is the old single-input format. JetFormBuilder still reads it in old forms, but current versions have separate settings: you pick the query in QUERY ID and type property names into OPTION VALUE and OPTION LABEL.

Steps

1. Build and save the query first under WordPress Dashboard > JetEngine > Query Builder > Add New. Check that it actually returns items, for example by using it in a test Listing Grid.
2. Open the form in JetFormBuilder and select the Select, Radio or Checkbox field.
3. Set FILL OPTIONS FROM to Generate Dynamically.
4. In GENERATOR FUNCTION, pick the JetEngine generator that takes values from a Query Builder query.
5. In QUERY ID, select your query from the dropdown. You don't type a numeric ID here.
6. In OPTION VALUE, type the name of the field to save. For posts, use a real post field such as post_name or ID.
7. In OPTION LABEL, type the property visitors should see, for example post_title. OPTION VALUE ID plus OPTION LABEL post_title saves the post ID and shows the title, which is what the old 15|ID|post_title string did. CALCULATED FIELD is optional and only matters if a Calculated Field reads this field.
8. Update the form and load it on the front end.

When it works: the field lists one option per item the query returns, each option shows the OPTION LABEL property, and the submitted value matches OPTION VALUE.

Pitfalls

• Typo in OPTION VALUE. If the name isn't a real property of the query's items, the options come out blank or all carry the same empty value.
• Context-dependent queries. A query that filters by the current post or current user may return nothing on the page where the form is embedded. Test it with a static value first.
• Wrong query type. A Terms query returns term properties, not post fields. Match OPTION VALUE to the query type.

For a static list instead of a query, see our tip on how to add a country list to a JetFormBuilder select field.

2. Filters don't reach the listing (Query ID)

Two different IDs cause most of the confusion. Every query has a numeric post ID in the Query Builder list. Filters don't use it, and forms don't need it because you pick the query from a dropdown. JetSmartFilters uses the optional Query ID that you type yourself in the query's General Settings. That custom ID has to be identical in three places. Filling in only the filter is the most common reason a filter does nothing.

Steps

1. Go to JetEngine > Query Builder, open the query, and type a Query ID in General Settings, for example featured_products. Lowercase letters and underscores, no spaces, keep it easy to copy. Save with Update Query.
2. Edit the page. In the Listing Grid, open the Custom Query section, turn on Use Custom Query, and select the query.
3. In the same Listing Grid, open the Advanced tab and paste featured_products into the CSS ID field.
4. In the JetSmartFilters filter widget, set This filter for = JetEngine, Apply type = AJAX or Mixed, Apply on = Value change, and paste featured_products into its Query ID field.
5. Save and test on the front end.

When it works: changing the filter reloads only that Listing Grid through AJAX and shows the matching items.

Two listings on one page

Say a page has one grid of blog posts and one grid of a custom post type. If neither query has its own Query ID, a filter can end up affecting both. Give each query a unique Query ID, put each ID in its own grid's CSS ID, and point each filter at the ID of the grid it should control.

If you filter on a text meta field with a Select filter, our answer on filtering by a custom meta field with a select filter covers the filter side.

3. Sorting by a meta field without a named clause

To sort by price, rating or any custom field, a plain meta query plus a generic order setting often fails. JetEngine needs to know which meta clause to sort by, and that clause needs a name.

Steps

1. In the query, open the Meta Query tab and click Add new clause.
2. Fill in Field key/name with the raw meta key, for example price. Use the field's name as stored in the database, not its label.
3. Set Compare and Value as needed, for example Greater than (>) and 0.
4. Set Type to Numeric for numbers. Without it, values are compared as text.
5. Give the clause a name, for example price_sorting.
6. Open Order & Order By and click Add new sorting parameter.
7. Set Order By to Order by meta clause, choose price_sorting as the meta clause, and set the order (ascending or descending).
8. Click Update Query.

When it works: prices run 9, 10, 100 rather than 10, 100, 9.

Pitfalls

• Text sorting. WordPress stores meta values as strings. If Type is left as text, 100 sorts before 20.
• Prefixed or labelled keys. Field key/name must be the exact meta key. A label like "Price" or a key with an extra prefix returns no matches.
• Missing values. Posts without that meta key don't match the clause, so they drop out of the results. Make sure every post you want listed has a value.

4. Archive pages built on a fixed Posts query

Building one Posts query per category doesn't scale, and a single Posts query on an archive template shows the same items on every category page. Current WP Query uses the native WordPress query of the page being viewed. On the Cars category it shows cars. On Bikes it shows bikes. One query covers every archive.

Steps

1. Create a query under JetEngine > Query Builder > Add New and set Query Type to Current WP Query.
2. Click Add new page type, choose a Page Type such as Categories, and set the number of posts for it. Add more page types if the template serves other archives.
3. Save with Add/Update Query.
4. Open your archive template. Crocoblock's own example uses a JetThemeCore archive template. In the Listing Grid, open Custom Query, turn on Use Custom Query, and select the new query.
5. Check two different category URLs on the front end. The editor preview has no category context, so it isn't a reliable test.

When it works: each category URL lists only its own posts, with the posts-per-page count you set for that page type.

The posts number you set changes the main WordPress query for that page type across the whole site, even on archives that don't use this query. If two Current WP Queries cover the same page type, only the last one counts.

5. REST endpoints with hard-coded limits

A query can be exposed as a REST endpoint for a mobile app or headless front end. A fixed Posts Per Page value means the app can't ask for more or fewer items. The fix is a Query Argument on the endpoint, mapped to a query parameter. An argument that isn't mapped does nothing.

Steps

1. In the query's General Settings, turn on Register Rest API Endpoint.
2. Set Endpoint Namespace (the first URL segment after wp-json), for example my, and Endpoint Path (the second segment), for example list-of-posts. The Rest API Endpoint URL field shows the result.
3. Choose Restrict Access: Is public. No restrictions, Users with selected capabilities (comma-separated capabilities in Access Capability; the user needs at least one), or Users with selected roles (Access for Roles).
4. Under Query Arguments, add an argument named posts-count with a Default Value of 2.
5. Open the Pagination tab. Next to Posts Per Page, click the Dynamic Tag icon, choose Query Variable, and enter posts-count as the Variable Name. In fields that accept macros, you can use %query_var|posts-count% instead.
6. Click Update Query. The Example of Rest API Endpoint URL with Query Arguments now appears.

Test the endpoint in a browser or API client:

https://example.com/wp-json/my/list-of-posts/?posts-count=5

When it works: the response contains five items. Without the parameter, you get the default of two. The URL parameter must match the registered argument name exactly. ?page-count=5 is silently ignored when the argument is posts-count.

Restricted endpoints and 401/403 errors

With capability or role restrictions, every request has to carry authorization. WordPress Application Passwords work well. Create one under Users > Profile > Application Passwords for a user who has the required role or capability, then send it with Basic auth over HTTPS:

curl -u "api-user:abcd efgh ijkl mnop qrst uvwx" "https://example.com/wp-json/my/list-of-posts/?posts-count=5"

A 401 or 403 means the credentials are missing or wrong, or the user lacks the capability or role you selected. Public endpoints return their data to anyone, so only leave an endpoint public if everything it returns is meant to be public.

Troubleshooting checklist

• Results don't change after edits. Cache Query is on by default. Turn it off in General Settings, retest, and turn it back on once the query is correct.
• Grid ignores your query. The Listing Grid's Posts Query, Terms Query, Users Query and Content Types Query tabs are legacy. Build the query in Query Builder and select it under Custom Query with Use Custom Query on.
• Merged Query sorts or paginates oddly. Merged Query has no unified sorting across the combined results. It may not work with pagination or the JetSmartFilters Indexer. If you need those, use one query that covers all the content instead.
• Query works in one widget but not another. Query Builder queries work in Listing Grid, Map Listing, Dynamic Chart, Dynamic Table, the JetBlog widgets, JetElements Advanced Carousel and Advanced Map, and the Bricks Query Loop. Check that the widget you use is on that list.
• Query type missing from the dropdown. Some types only appear when their plugin or module is active. For example, REST API Query needs the Rest API Listings module.
• Slow pages. Query Builder doesn't make a site faster by itself. Speed comes from asking for less: sensible posts-per-page values, fewer meta clauses, and caching once the results are correct.
• Security. Keep JetEngine updated, especially on sites that use SQL queries or public endpoints.

Most broken Query Builder setups come down to one mismatched field. That might be an ID missing from the CSS ID, a clause without a name, or an argument name that differs by one word. Use the table at the top to find yours. If you'd rather have a developer audit your queries, filters and endpoints, post a request on BoostMyCroco.