Troubleshooting Guide

This chapter covers the following topics.

Locating the source of the problem

In a Structr application many different components work together in different ways. There are loosely coupled parts that are connected by convention and directly connected elements that influence each other’s behaviour. There are many different layers that can be the source of a problem, and oftentimes the type of an error or unexpected behavior can hint at the solution.

Log file

The definitive place to look for error messages is the log file. Structr will write almost everything that is an error or warning message into the log, depending on some configuration settings. In addition to warning and error messages, Structr also logs informative messages, for example the licensing configuration, information about services, etc.

If you want to use the log file in your application, you can use the built-in function log which allows you to write arbitrary messages into the file.

It is always a good idea to look into the log file when developing an application with Structr.

You can find a growing list of error messages, descriptions and possible solutions in the Exceptions section below.

Troubleshooting your Application

This section contains an overview of possible ways to identify errors in your Structr application.

HTTP Response / Status Codes

In Your Web Browser

If you encounter problems in a Structr application that you use with your browser, the actual error messages are likely to be hidden in the Developer Console. In most modern browers, you can open the “Developer Tools” to have a look at the internal processes and requests that the browser makes to load a page etc. The developer console is a good place to start looking for possible error codes or messages if your Structr application does not behave as expected.

REST Errors

When you use HTTP to make a call against one of the REST endpoints, Structr will return a status code and - in case of errors - a detailed response message.

2XX Success
HTTP status code HTTP Status Text Description
200 OK No error, the request was successful (there can still be output in the log file)
201 Created No error, the request was successful (an object was created)
4XX Client Errors

If you encounter a client error, it is probably your fault, because you didn’t supply the correct information to the server. Possible causes are missing authentication information, wrong password, wrong visibility flags, and most importantly: wrong data. Structr uses the status code 422 (Unprocessable Entity) extensively to signal to the user that the content of a request was not accepted, either because of schema contraints, or because the data has the wrong structure or format.

HTTP status code HTTP Status Text Description
400 Bad Request Client error, the request is not valid and should not be repeated
401 Unauthorized Client error, the request needs a user
403 Forbidden Client error, the request needs a user
404 Not Found Client error, access to non-existing resource (can be simply invisible)
405 Bad Method Client error, access to an endpoint using the wrong HTTP verb
422 Unprocessable Entity Client error, data format error, structural error, schema constraint violation etc.
5XX Server Errors

If you encounter a server errors, it is probably not your fault. Server errors indicate a malfunction or misconfiguration on the server side, which can range from wrong configuration settings to bugs in Structr.

HTTP status code HTTP Status Text Description
500 Server Error Server error, unspecified cause
503 Service Unavailable Server error, temporary failure

Validation Errors

As described in other chapters, Structr allows you to define constraints on the types created in the schema. When a request to any of the interfaces modifies the data in a way that violates those constraints, the request fails and an error message with the HTTP status code 422 (Unprocessable Entity) is returned.

Constraints on built-in types

The base data model already defines a number of constraints on internal fields. The value of the id property of any object must be unique. If a request tries to create an object with an existing UUID, the following error message is returned.

{
  "code": 422,
  "message": "Unable to commit transaction, validation failed",
  "errors": [
    {
      "type": "User",
      "property": "id",
      "token": "already_taken",
      "detail": "e4d143a18aca4842b2dc6b40a4b76490"
    }
  ]
}

Output on the page

If you use template expressions and built-in functions in a content element, and an error occurs, the error message will be written into the HTML output. If there is an error message on the page, or a usage message for a built-in function, the error is very likely in a dynamic content element in that page.

Missing elements, Page not found?

One of the first problems you will encounter when building a multi-user application has to do with the visibility of elements. There are two flags that govern the visibility of elements in a Structr page, which you can read more about clicking the highlighted parts of this paragraph.

Scripting Errors

Errors in scripting expressions, schema methods or templates will almost always be written to the log file. You will see output similar to the example below, which tells you a lot of things if examined closely.

2020-03-31 22:01:31.141 [pool-1-thread-902] WARN  org.structr.core.script.Scripting - Exception in Scripting context
org.mozilla.javascript.EvaluatorException: syntax error (Template.script source ["Search Results Main Content":6c9c352dbf264a6a95924e9dd597b6b5]#53)
        at org.mozilla.javascript.DefaultErrorReporter.runtimeError(DefaultErrorReporter.java:79)
        at org.mozilla.javascript.DefaultErrorReporter.error(DefaultErrorReporter.java:66)
        at org.mozilla.javascript.Parser.addError(Parser.java:259)
        at org.mozilla.javascript.Parser.reportError(Parser.java:327)
        at org.mozilla.javascript.Parser.reportError(Parser.java:314)
        at org.mozilla.javascript.Parser.reportError(Parser.java:307)
        at org.mozilla.javascript.Parser.primaryExpr(Parser.java:3198)
        at org.mozilla.javascript.Parser.memberExpr(Parser.java:2740)
        at org.mozilla.javascript.Parser.unaryExpr(Parser.java:2634)
        [...]

The most important part is this one, which we will break down into its components.

org.mozilla.javascript.EvaluatorException: syntax error (Template.script source ["Search Results Main Content":6c9c352dbf264a6a95924e9dd597b6b5]#53)
Error type
org.mozilla.javascript.EvaluatorException: syntax error

It tells you the type of error (syntax error), which in this case is triggered by a superfluous parenthesis in a server-side JavaScript template expression.

Error location
(Template.script source ["Search Results Main Content":6c9c352dbf264a6a95924e9dd597b6b5]#53)

The location of the error is a Template element with UUID 6c9c352dbf264a6a95924e9dd597b6b5 and name Search Results Main Content, line number 53.

With this information at hand, you should be able to investigate and fix the problem by finding the erroneous element and the line number within that element / script.

Schema Errors

Enum Property

The possible values of an Enum Property are defined in the schema/code area in the Format/Code field of the property. The values have to be provided as a comma-separated list.

Because Structr dynamically creates Java code from the format definition, the following limitations apply:

  • Enum-values must be simple alpha-numeric strings (i.e. no special characters, no spaces, etc)
  • Reserved words (like “boolean”, “final”, etc) are not allowed

This is not enforced by Structr but by Java itself as curating a comprehensive blacklist would not be feasible.

Known Issues

A list of problems that people had, and the solutions, grouped by source.

Functional Issues

Search / Sorting via REST doesn't work

If search / sorting via REST doesn’t work, the search key is probably not indexed, or it is a FunctionProperty that lacks a type hint.

Things to check
  • is the property key set to indexed in the schema?
  • if it is a FunctionProperty, is the type hint set?

Unable to log in - Too many failed login attempts

By default, Structr auto-locks an account after 4 incorrect login attempts. Further login attempts (even with the correct password) result in the error message “Too many failed login attempts”. This security setting can be configured via the configuration setting security.passwordpolicy.maxfailedattempts. The default is 4 and the functionality is disabled for any number less than or equal to 0.

The number of failed login attempts is stored in the user node in the attribute passwordAttempts. Setting this attribute to 0 enables the user to log in again.

This can be done using the superadmin credentials (or any other admin account) by sending a PUT request to the appropriate resource (/structr/rest/User/[UUID_OF_USER]) with the body {"passwordAttempts":0}. It can also be solved by temporarily changing the setting to 0 and logging in.

Setup Issues

Java Development Kit (JDK) vs. Runtime Environment (JRE)

Structr requires a complete JDK because classes are compiled at runtime. A JRE is therefore not sufficient and prevents Structr from starting successfully.

In older versions, this used to require a full JDK. In newer versions it requires GraalVM.

Log messages

Non-indexed property key ... is used in query
WARN  o.s.core.graph.search.SearchCommand - Non-indexed property key Paragraph.content is used in query. This can lead to performance problems in large databases.

An informative message that warns of possible performance problems when the amount of data in the database increases. Objects can be found based on their property value without an index, but searching can become very slow in large databases. You should consider enabling the indexed flag for the property mentioned in the warning message.

Unknown property ... in non-graph properties, ignoring.
WARN  org.structr.schema.SchemaHelper - Unknown property articleCount in non-graph properties, ignoring.

This is a warning message that indicates a forgotten property. It can be safely ignored.

No resource access grant found for..
INFO  org.structr.web.auth.UiAuthenticator - No resource access grant found for signature 'Project/finishTask' (URI: /structr/rest/Project/cdad015cd9f74225a2dbf82158aac8d9/finishTask)

The Resource Access Grant with the signature Project/finishTash does not exist. You must create and configure a Resource Access Grant object with the given signature to allow the request.

Resource access grant found for ... but method ... not allowed
INFO org.structr.web.auth.UiAuthenticator - Resource access grant found for signature /Project, but method PUT not allowed for public users.

The Resource Access Grant with the signature /Project is missing the PUT flag. You can add the flag in the Security section of the Structr UI.

Resource chain evaluation for path /globalSchemaMethods/... resulted in 2 entries, returning status code 400
WARN  o.s.rest.servlet.ResourceHelper - Resource chain evaluation for path /globalSchemaMethods/customCleanupFunction resulted in 2 entries, returning status code 400

Calling the global schema method customCleanupFunction via the globalSchemaMethods resource is only possible if the method itself is visible to the user making the request. If anonymous users should be able to make the request, the method needs to have the visibleToPublicUsers flag set to true. If authenticated users should be able make the request, the method needs to have the visibleToAuthenticatedUsers flag set to true.

After that the normal procedure of creating/configuring a resource access grant still needs to be done.

Cannot connect to Neo4j database server at <your-server-address>: Database does not exist. Database name: 'neo4j'.

The reason for this is that, since version 4.1-SNAPSHOT, structr supports connecting to different neo4j databases. The database name has to be configured though. By default the database name is set to “neo4j” (because that is the default database name since neo4j 4.x). If your application started with an older version of neo4j, then the database name might be “graph.db”. If you have configured a different name, then that name has to be used.

The configuration for this is done in structr.conf. A new configuration line has to be added to the existing configuration.

Let us assume the configuration looks like this:

XXXXXXXXXX.database.connection.name = <a name for your connection>
XXXXXXXXXX.database.connection.password = <your database user password>
XXXXXXXXXX.database.connection.url = <your connection string>
XXXXXXXXXX.database.connection.username = <your database username>

XXXXXXXXXX is the custom prefix in your settings.

The new line would need to match the XXXXXXXXXX and look like this:

XXXXXXXXXX.database.connection.databasename =

REST Responses

400 Bad Request: User self-registration is not configured yet, cannot create new user.

You need to enable and configure user self-registration according to https://docs.structr.com/docs/handling-user-sessions#user-self-registration

Exceptions

IllegalStateException: URI has an authority component

Symptom

Accessing any file in a Structr instance results in a 500 Server Error message.

Example log snippet
2020-03-31 12:33:56.703 [qtp1327213994-88] WARN  org.eclipse.jetty.server.HttpChannel - /resources/script.js
java.lang.IllegalArgumentException: URI has an authority component
        at java.base/sun.nio.fs.UnixUriUtils.fromUri(UnixUriUtils.java:53)
        at java.base/sun.nio.fs.UnixFileSystemProvider.getPath(UnixFileSystemProvider.java:103)
        at java.base/java.nio.file.Path.of(Path.java:203)
        at java.base/java.nio.file.Paths.get(Paths.java:97)
        at org.structr.web.entity.AbstractFile.defaultGetFileOnDisk(AbstractFile.java:257)
        at org.structr.web.entity.Folder.getFileOnDisk(Folder.java:205)
        at org.structr.dynamic.Folder.getFileOnDisk(Folder.java:95)
Solution

Make sure that structr.conf does not override settings for db.path and files.path, or, if the settings are present, don’t begin with ./.