🔧 Troubleshooting Queries

Query Errors Before 180-Second Timeout

Check the following possible causes:

A query runs for awhile, then an error occurs, well before the 180 second timeout

There are other timeouts that might need to be configured:

...

• PHP timeout:

• default_socket_timeout in php.ini

...

• might be too small.
• Apache/IIS timeout

...

• : May be shorter than expected.
• Wildfly worker thread pool: Might be too small.
• IIS

...

• PHP FastCGI Activity Timeout

...

• : Often set to

...

• 30s by default.
  (Go to IIS

...

The webclient keeps saying "The PM Cell or the address in the properties file is incorrect."

Try these possible fixes:

1. Check that the URL for the PM cell that is specified in i2b2_config_data.js in the root directory of the webclient is set correctly.
2. SELinux might be on and causing access problems. (If this is the problem, /var/log/audit/audit.log will have DENY messages.)
   1. Option 1 (not recommended): turn off SELinux - Run sudo setenforce 0. (Only works until reboot.)
   2. Option 2 (preferred): turn off the SELinux network connect protection - setsebool -P httpd_can_network_connect 1 (Persists across reboots.)

A user is locked out and I want to restore their access

...

• → FastCGI Settings → Edit)

Tips for Optimizing i2b2 Query Speed

PostgreSQL:

• Avoid using % in concept codes (it prevents index usage).
• Consider table partitioning for large datasets.

SQL Server (MSSQL):

• Use clustered columnstore indexes on the observation_fact table.

All Platforms:

• For extremely large observation_fact tables, consider splitting into multiple fact tables.

i2b2 running with SHRINE:

• Some sites have found that truncating pm_user_login and pm_user_session dramatically speeds up queries. These can be rotated (backed up and truncated) on a regular basis to keep queries fast. pm_user_login is an audit log of login events, and pm_user_session tracks active sessions. (Note that completely truncating pm_user_session will log out all users.)

...

🔐 Access & Authentication

I Can Log In, but Nothing Else Works

• Check Wildfly logs for "invalid session" errors.
  → Your database and Wildfly servers might have different system time settings.
  Ensure both the time and timezone match.

A User is Locked Out — How to Restore Access

• Run:

  DELETE FROM pm_project_user_params WHERE user_id='[your user]' AND param_name_cd='LOCKEDOUT';
  

• Obfuscated users

...

• may be locked out

...

• after repeating the same query

...

• too often (default is 7 times).
  → Controlled by edu.harvard.i2b2.crc.lockout.setfinderquery.count

...

• in

...

• hive_cell_params

...

• .

To allow a the user to repeat rerun the same query after the lockout number of attempts, you must delete the previous queries from the query that locked them out, delete entries from:

DELETE FROM qt_query_master

...

 WHERE user_id = '[user_id]';

Using Active Directory with SQL Server

Update db.properties:

<connection-url>jdbc:sqlserver://localhost:1433;IntegratedSecurity=true;Trusted_Connection=Yes</connection-url>

• Leave the <password> field empty — it will be ignored.

...

🌐 Webclient Issues

PM Cell or Address is Incorrect

Troubleshooting steps:

• Check that the URL for the PM cell is correct in i2b2_config_data.js.
• SELinux may be blocking access.
  Check /var/log/audit/audit.log for DENY messages.

Solutions:

• Not Recommended: Disable SELinux:
  sudo setenforce 0 (resets on reboot)
• Preferred: Allow network connect:
  setsebool -P httpd_can_network_connect 1 (persistent)

...

📊 Encounter Sets and Breakdown Failures

Encounter Set Breakdowns Fail, Others Work

...

Encounter set breakdowns fail but other breakdowns work fine

Check that your QT_Patient_enc_collection has less than two billion rows. If it grows too large over time, generating new encounter sets will fail. Delete unneeded encounter sets.

...

• Check row count in QT_PATIENT_ENC_COLLECTION:

• SELECT max(PATIENT_ENC_COLL_ID) FROM 

...

• QT_PATIENT_ENC_COLLECTION

...

I want to use https on the Wildfly side (to communicate with the i2b2 cells)

...

• ;
  

• If it has over 2 billion rows, generating new sets will fail.
  → Solution: Delete old or unneeded encounter sets.

...

🔐 HTTPS and Inter-cell Communication

Using HTTPS with Wildfly (Inter-cell SSL)

• Enable Inter-cell SSL to secure communication between i2b2 cells.
  → See the 1.7.11 Release Notes for setup instructions.

I want to use Active Directory in SQLServer

If you are using SQL Server, it is possible to use Active Directory accounts for the database users (i.e., Integrated Login) in the db.properties files. To enable this, replace

<connection-url>jdbc:sqlserver://localhost:1433</connection-url>

with 

<connection-url>jdbc:sqlserver://localhost:1433;IntegratedSecurity=true;Trusted_Connection=Yes</connection-url>

Then the password field in the <security> section will be ignored and the SQLServer integrated security will be used.

...

🤝 Contributing to i2b2

How to Contribute

1. Create a JIRA issue
2. Make a GitHub pull request Pull Request and reference the JIRA issue in the commit comment
   (e.g., "CORE-589: Fixed hyperspeed drive rotor").
3. Attest to the DCO (can be done by including text like e.g., include:
   'I attest to to https://developercertificate.org/' in the Pull Request)
4. E-mail someone on the i2b2 core development team (Email a core developer (e.g., Mike Mendis or Jeff Klann at the time of writing).

Additionally, your Your contribution must:

...

• Be tested

...

• Include unit tests (for new features)

...

• Include documentation (can be

...

• in the

...

Tips for Optimizing i2b2 query speed

Postgres

1. Do not use '%' in any concept code. In Postgres, this is known to prevent the database from using indexes.
2. In Postgres, consider using table partitioning

MSSQL

1. Use clustered columnstore indexes for the fact table.

All platforms

1. If your fact table is extremely large, consider splitting it into multiple fact tables.
2. ... more to come...

I can log in, but nothing else works. On the server, I see a lot of "invalid session" errors in the Wildfly log

...

• PR)