Note: This documentation is for the development version of X3DOM. Released versions: 1.5, 1.4, 1.3, 1.2.


As with most software systems, something can go wrong. But fear not. There are a couple of things you can check and try. You’ll find some hints and tips here.

Common problems

I am not seeing anything

Assuming we are not dealing with an electrical or vision problem:

  • Check if your HTML and X3D code is correct
  • If you are using the HTML5 doctype make sure all X3D tags are properly closed. You can not use “self-closing” syntax. Instead you need to close the tag explicitly: <color ...></color> NOT <color ... />
  • For the HTML part, swing by the W3C validator to check for syntax errors

There are weird chars or some gobbledygook on my web page

This is most likely an encoding problem or errors generated by using unsuited editors or HTML export tools (looking at you Word). Gobbledygook may be caused by improperly closed tags (see above).

  • Check if you file encoding is OK. UTF-8 is recommended unless otherwise required.
  • Use a HTML meta to denote the file encoding and make sure your file endcoding matches your meta tag.
  • In case you are serving your files from a web server: make sure the server sets proper HTTP headers (especially mimetype and encoding) and middleware does not alter the file encoding (PHP et al. are sources for messing up multi-byte encodings). Again, maintaining UTF-8 throughout is a sensible choice (also read this).

How to ask Questions

In order to analyze and debug your problem, please be more specific about the nature of your problem. Before you sit down and write a mail or forum post, it is helpful to ask yourself these questions and include this info in your question/report:

  • What exactly is not working?
  • Is it really an error or are you just unhappy with aesthetics?
  • What errors do you get?
  • Can you reproduce this behavior in an isolated testcase?
  • What did you try to solve your problem?

The following info is genuinely helpful in analyzing your problem:

  • OS, Version, Architecture
  • GPU type, driver versions
  • Output of about:gpu in Chrome
  • Browsers and versions you tried and the results
  • Log output of X3DOM (javascript console)
  • You can generate some of the information here

Also note that hot-linking x3dom.css/js should only be used for testing and development. Once you deploy your site, it is best to copy those files over to your server or a CDN. We can not guarantee that those URLs are stable and our network bandwidth is rather limited.

This his also a helpful page and a good read as well:

Table Of Contents

Related Topics