Troubleshooting and debugging

General tips on debugging Converse.js

When debugging converse.js, always make sure that you pass in debug: true to the converse.initialize call.

Converse.js will then log debug information to the browser’s developer console. Open the developer console and study the data that is logged to it.

Strope.js the underlying XMPP library which Converse.js uses, swallows errors, so that messaging can continue in cases where non-critical errors occur.

This is a useful feature and provides more stability, but it makes debugging trickier, because the app doesn’t crash when something goes wrong somewhere.

That’s why checking the debug output in the browser console is so important. If something goes wrong somewhere, the error will be logged there and you’ll be able to see it.

Additionally, Converse.js will in debug mode also log all XMPP stanzas (the XML snippets being sent between it and the server) to the console. This is very useful for debugging issues relating to the XMPP protocol.

For example, if a message or presence update doesn’t appear, one of the first things you can do is to set debug: true and then to check in the console whether the relevant XMPP stanzas are actually logged (which would mean that they were received by Converse.js). If they’re not logged, then the problem is more likely on the XMPP server’s end (perhaps a misconfiguration?). If they are logged, then there might be a bug or misconfiguration in Converse.js.

Conflicts with other JavaScript libraries


You are using other JavaScript libraries (like JQuery plugins), and get errors like these in your browser console:

Uncaught TypeError: Object [object Object] has no method 'xxx' from example.js


First, find out which object is referred to by Object [object Object].

It will probably be the jQuery object $ or perhaps the lodash/underscore object _.

For the purpose of demonstration, I’m going to assume its $, but the same rules apply if its something else.

The bundled and minified default build of converse.js, converse.min.js includes within it all of converse.js’s dependencies, which include for example jQuery.

If you are having conflicts where attributes or methods aren’t available on the jQuery object, you are probably loading converse.min.js (which includes jQuery) as well as your own jQuery version separately.

What then happens is that there are two $ objects (one from converse.js and one from the jQuery version you included manually) and only one of them has been extended to have the methods or attributes you require.

Which jQuery object you get depends on the order in which you load the libraries.

There are multiple ways to solve this issue.

Firstly, make sure whether you really need to include a separate version of jQuery. Chances are that you don’t. If you can remove the separate version, your problem should be solved, as long as your libraries are loaded in the right order.

Either case, whether you need to keep two versions or not, the solution depends on whether you’ll use require.js to manage your libraries or whether you’ll load them manually.

With require.js

Instead of using converse.min.js, manage all the libraries in your project (i.e. converse.js and its dependencies plus all other libraries you use) as one require.js project, making sure everything is loaded in the correct order.

Then, before deployment, you make your own custom minified build that bundles everything you need.

With <script> tags

Take a look at non_amd.html in the converse.js repo.

It shows in which order the libraries must be loaded via <script> tags. Add your own libraries, making sure that they are loaded in the correct order (e.g. jQuery plugins must load after jQuery).

Performance issues with large rosters

Effort has been made to benchmark and optimize converse.js to work with large rosters.

See for example the benchmarking tests in spec/profiling.js which can be used together with the profiling features of Chrome to find bottlenecks in the code.

However, with large rosters (more than 1000 contacts), rendering in converse.js slows down a lot and it may become intolerably slow.

One simple trick to improve performance is to set show_only_online_users: true. This will (usually) reduce the amount of contacts that get rendered in the roster, which eases one of the remaining performance bottlenecks.