path: root/htdocs/docs/errors.html

<!--#set var="revision" value="\$Id: errors.html,v 1.13 2001-09-19 08:52:09 link Exp $" -->
<!--#set var="date" value="\$Date: 2001-09-19 08:52:09 $" -->
<!--#include virtual="/header.html" -->

    <p>
      These error explanations were originally written by Scott Bigham,
      they are used here with his permission.
    </p>

    <dl>
      <dt><a id="undef-id" name="dup-id">"ID "FOO" already defined"</a></dt>
      <dd>
        <p>
          You have defined the id/name "FOO" more then once. You will also get
          a message telling you where it was first defined. Be aware that this
          message may be the result of an ambiguity in the specification.
          While user-agents must treat values of the id attribute
          as case-sensitive, they must still be case-insensitive unique in the
          document. See
          <a href="http://www.w3.org/TR/html4/struct/links.html#h-12.2.1">Section
          12.2.1 Syntax of anchor names</a> in the HTML 4.01 Reccomendation
          for further information.
        </p>
      </dd>
      <dt><a id="unterm-comment-1" name="unterm-comment-1">"entity end not allowed in comment"</a></dt>
      <dd>
        <p>
          Unterminated comment. The position indicator points to the very end of
          the file, where the problem was detected; to find the beginning of the
          comment, try searching for the last occurrence of
          `<code>&lt;!--</code>' in the document.
        </p>
      </dd>
      <dt><a id="unterm-comment-2" name="unterm-comment-2">"name start character invalid: only s and comment allowed in comment declaration"</a></dt>
      <dd>
        <p>
          Unterminated comments again. This time, you have a case like:
        </p>
        <pre>
          &lt;!-- This is the first unterminated comment &gt;
          &lt;!-- This is the second one &gt;
        </pre>
        <p>
          The validator (correctly) interprets the `<code>--</code>' in the
          second comment as terminating the first comment, and then interprets
          the text of the second comment as text between comments, which is not
          allowed.
        </p>
      </dd>
      <dt><a id="bad-comment" name="bad-comment">"unknown declaration type `FOO'"</a></dt>
      <dd>
        <p>
          Most likely an invalid comment of the form <code>&lt;!invalid
          comment&gt;</code>; the validator is (correctly) attempting to
          interpret it as an <a href="sgml.html#sgml">SGML</a> markup
          declaration.
        </p>
      </dd>
      <dt><a id="attr-quoted" name="attr-quoted">"an attribute value must be a literal unless it contains only name characters"</a></dt>
      <dd>
        <p>
          You have an attribute whose value needs to be in quotes. If an
          attribute value contains any character other than letters, digits,
          hyphens and periods, it must be enclosed in double quotes (single
          quotes would also be okay from an <a href="sgml.html#sgml">SGML</a>
          standpoint, but some browsers don't recognize them).
        </p>
      </dd>
      <dt><a id="attr-char" name="attr-char">"character `X' not allowed in attribute specification list"</a></dt>
      <dd>
        <p>
          The validator has found a character inside an HTML tag that isn't
          allowed there. This usually means you didn't put an attribute value in
          quotes when necessary. It also probably means that the character in
          question is not allowed in the value of the attribute at all, or you
          would have received the <a href="#attr-quoted">previous error</a>
          instead. See <a href="#bad-attr-char">below</a> for more information.
        </p>
        <p>
          You can also get in trouble by forgetting the closing quote on an
          attribute. For instance:
        </p>
        <pre>
          &lt;IMG SRC="http://foo.com/fred.gif&gt;
          &lt;IMG SRC="http://foo.com/joe.gif&gt;
        </pre>
        <p>
          The validator will (correctly) interpret this as a SRC value of
          <code>"http://foo.com/fred.gif&gt; &lt;IMG SRC="</code>, and then
          choke on the following `:'. In this case, the position indicator in
          the error message may be several lines below the line with the missing
          quote.
        </p>
      </dd>
      <dt><a id="name-length" name="name-length">"length of attribute value must not exceed LITLEN less NORMSEP (1022)"</a></dt>
      <dd>
        <p>
          This usually occurs in conjunction with the
          <a href="#attr-char">previous error</a>. It almost always means that
          you've forgotten a closing quote on an attribute value. For instance,
          in:
        </p>
        <pre>
          &lt;IMG SRC="fred.gif&gt;
          &lt;!-- 50 lines of stuff --&gt;
          &lt;IMG SRC="joe.gif"&gt;
        </pre>
        <p>
          The SRC value for the first <code>&lt;IMG&gt;</code> is the entire
          fifty lines of stuff up to the next double quote, which probably
          exceeds the <a href="sgml.html#sgml">SGML</a>-defined length limit for
          HTML string literals. Note that the position indicator in the error
          message points to where the attribute value <em>ended</em> &mdash; in
          this case, the <code>"joe.gif"</code> line.
        </p>
      </dd>
      <dt><a id="undef-tag" name="undef-tag">"element `FOO' undefined"</a></dt>
      <dd>
        <p>
          You've used an unknown tag (represented here by FOO). Make sure the
          DTD indicated by your DOCTYPE actually includes this element.
        </p>
        <p>
          If the tag in question is a frame-related tag you must use the
          "Frameset" DTD, and if you use (deprecated) physical markup ("FONT"
          and friends) you must use the "Transitional" DTD.
        </p>
      </dd>
      <dt><a id="not-allowed" name="not-allowed">"document type does not allow element "FOO" here"</a></dt>
      <dd>
        <p>
          Straightforward, but not terribly informative. There are a
          <em>lot</em> of different errors that will generate this error
          message:
        </p>
        <ul>
          <li>
            Using an unknown tag. In this case, the next error will be
            <a href="#undef-tag">"element `FOO' undefined"</a>.
          </li>
          <li>
            Using a tag in the wrong place. For instance,
            <code>&lt;TABLE&gt;&lt;TD&gt;blah&lt;/TABLE&gt;</code> will cause
            this error. The trick here is that <code>&lt;TABLE&gt;</code> cannot
            <em>directly</em> contain <code>&lt;TD&gt;</code>'s; it contains
            <code>&lt;TR&gt;</code>'s which contain <code>&lt;TD&gt;</code>'s.
            The above example should be
            <code>&lt;TABLE&gt;&lt;TR&gt;&lt;TD&gt;blah&lt;/TABLE&gt;</code>.
          </li>
        </ul>
      </dd>
      <dt><a id="not-contained" name="not-contained">document type does not allow element "FOO" here; assuming missing "BAR" start-tag</a></dt>
      <dd>
        <p>
          Similar to the <a href="#not-allowed">previous error</a>, but more
          specific: in this case, you have a FOO element that is not contained
          in a BAR element when FOO is not allowed outside of BAR. Some of the
          most common causes of this error are:
        </p>
        <ul>
          <li>
            Using the <code>DD</code> element as a fake paragraph indent.
            <code>DD</code> is not allowed outside of a <code>DL</code> element.
          </li>
          <li>
            Improper construction of a nested list. An inner UL or OL in a
            nested list may not appear directly within an outer UL/OL, but only
            within an LI of the outer UL/OL, as in the following example:
            <pre>
        &lt;OL&gt;
          &lt;LI&gt;Obtain the following items:
            &lt;UL&gt;
              &lt;LI&gt;Ham&lt;/LI&gt;
              &lt;LI&gt;Bread; one of:
                &lt;UL&gt;
                  &lt;LI&gt;White&lt;/LI&gt;
                  &lt;LI&gt;Rye&lt;/LI&gt;
                  &lt;LI&gt;Whole wheat&lt;/LI&gt;
                &lt;/UL&gt;
              &lt;/LI&gt;  &lt;!-- End of the "Bread" &lt;LI&gt; --&gt;
              &lt;LI&gt;Cheese&lt;/LI&gt;
            &lt;/UL&gt;
          &lt;/LI&gt;  &lt;!-- End of the "Obtain" &lt;LI&gt; --&gt;
          &lt;LI&gt;Place ham and cheese between two slices of bread&lt;/LI&gt;
          &lt;LI&gt;Consume the resulting ham-and-cheese sandwich&lt;/LI&gt;
        &lt;/OL&gt;
            </pre>
            <p>
              The <code>&lt;/LI&gt;</code> end tags are optional and are only
              included above to emphasize how the structure of the nested list
              is arranged; if you omit them, the parser will infer their
              presence in the locations shown above. 
            </p>
          </li>
        </ul>
        <p>
          The validator has inserted a BAR start tag where it thinks there needs
          to be one; it will probably complain later on that <a href="#no-end-tag">the
          corresponding end tag is also missing</a>.
        </p>
      </dd>
      <dt><a id="attr-undef" name="attr-undef">"there is no attribute `FOO' for this element (in this HTML version)"</a></dt>
      <dd>
        <p>
          You have used an attribute with an element that is defined not to have
          that attribute. This is most commonly caused by using
          vendor-specific attributes without setting the document type
          appropriately.
        </p>
      </dd>
      <dt><a id="undef-attr-val" name="undef-attr-val">"`FOO' is not a member of the group specified in the declared value of this attribute"</a></dt>
      <dd>
        <p>
          Similar to the <a href="#attr-undef">previous error</a>; this time,
          you're using an attribute that is defined for the element, but with a
          value that isn't defined for the attribute. For instance, the Netscape
          extension <code>&lt;IMG ALIGN=ABSMIDDLE&gt;</code> will cause this
          error; ABSMIDDLE isn't one of the allowed values for the ALIGN
          attribute of <code>&lt;IMG&gt;</code> (unless, of course, you provided
          a Netscape document type).
        </p>
        <p>
          If you're using the Netscape document type, the BORDER attribute of
          <code>&lt;TABLE&gt;</code> can cause this error.
        </p>
        <p>
          This error can also be caused, oddly enough, by missing close quotes
          on attribute values. For instance, given:
        </p>
        <pre>
          &lt;IMG SRC="fred.gif&gt; &lt;IMG SRC="joe.gif&gt;
        </pre>
        <p>
          The validator will (correctly) see a SRC attribute of
          <code>"fred.gif&gt; &lt;IMG SRC="</code>, and then try to interpret
          JOE.GIF as an attribute of <code>&lt;IMG&gt;</code>.
        </p>
      </dd>
      <dt><a id="bad-attr-char" name="bad-attr-char">"syntax of attribute value does not conform to declared value"</a></dt>
      <dd>
        <p>
          Yet another attribute error; this time, the attribute in question was
          defined to take a numeric value, or an <a
          href="sgml.html#sgml">SGML</a> identifier value, and you used a
          character that doesn't match what it was expecting.
        </p>
        <p>
          One potentially annoying source of this error is the <code>TD
          WIDTH</code> attribute. Whether intentionally or by oversight, the
          HTML 3.2 DTD defines this attribute to have a value type of NUMBER,
          which means that <code>&lt;TD WIDTH="50%"&gt;</code> is not allowed.
        </p>
      </dd>
      <dt><a id="attr-bad-name" name="attr-bad-name">"value of attribute "FOO" invalid: "#" cannot start a name"</a></dt>
      <dd>
      	<p>
	        A special case of <a href="#bad-attr-char">the previous error</a>; the
	        attribute in question is defined to take as value an SGML name token,
	        which must begin with a letter.
				</p>
      </dd>
      <dt><a id="bad-abbrev-attr" name="bad-abbrev-attr">"`FOO' is not a member of a group specified for any attribute"</a></dt>
      <dd>
        <p>
          Another attribute error, this time referring to an "abbreviated"
          attribute. <a href="sgml.html#sgml">SGML</a> allows you to omit the
          name of an attribute if the attribute value is unambiguous. For
          instance, <code>&lt;IMG ISMAP&gt;</code> is actually an abbreviation
          of <code>&lt;IMG ISMAP=ISMAP&gt;</code>. (Technically, this also means
          that e.g. <code>&lt;P ALIGN=CENTER&gt;</code> could be abbreviated to
          <code>&lt;P CENTER&gt;</code>, but it is unlikely that current
          browsers will get this right.) The validator has found something that
          looks like an abbreviated attribute but doesn't match the value of any
          attribute for this element. For instance, a typo like <code>&lt;IMG
          ISNAP&gt;</code> would produce this error.
        </p>
        <p>
          A missing close quote on a previous attribute value can also trigger
          this error if the next quote it finds is followed by something that
          looks like an abbreviated attribute; for instance, <code>&lt;IMG
          SRC="fred.gif&gt;&lt;IMG SRC="joe.gif&gt;</code> would produce this
          error, referring to the "attribute value" <code>JOE.GIF</code>.
        </p>
      </dd>
      <dt><a id="attr-missing" name="attr-missing">"required attribute `FOO' not specified"</a></dt>
      <dd>
        <p>
          You left off a required attribute of the indicated element. The most
          common such omitted attribute is the <code>ALT</code> attribute of the
          <code>AREA</code> or <code>IMG</code> element; browsers will typically
          use these to build a menu equivalent to your client-side imagemap if
          the user has disabled image loading, so you'll want to use a
          meaningful value here.
        </p>
      </dd>
      <dt><a id="no-end-tag" name="no-end-tag">"end tag for `FOO' omitted, but its declaration does not permit this"</a></dt>
      <dd>
        <p>
          You forgot to close something. FOO is the element you forgot to close
          (and the next message, `start tag was here' points to the particular
          instance of FOO in question); the positional indicator points to where
          the validator expected you to close the element. There are a few
          common ways that this can happen:
        </p>
        <ul>
          <li>
            You've put something inside the FOO element that isn't allowed
            there. For instance, <code>&lt;UL&gt;&lt;LI&gt;&lt;H4&gt;fake font
            change&lt;/H4&gt;&lt;/UL&gt;</code> will cause this error, since
            headers aren't allowed inside <code>&lt;UL&gt;</code>'s; the
            validator assumes that you meant to close the
            <code>&lt;UL&gt;</code> before opening the <code>&lt;H4&gt;</code>.
          </li>
          <li>
            Interlocked elements. For instance,
            <code>&lt;B&gt;&lt;I&gt;nope&lt;/B&gt;&lt;/I&gt;</code> will cause
            this error. HTML requires that you close elements ``inside-out'' ---
            that is, the last element you opened is the first element you should
            close. In this example, you'd have to close the
            <code>&lt;I&gt;</code> before the <code>&lt;B&gt;</code>.
          </li>
          <li>
            Unclosed <code>&lt;A&gt;</code> tags. Yes, even <code>&lt;A
            NAME="foo"&gt;</code> has to have a corresponding
            <code>&lt;/A&gt;</code>. Note that an empty <code>&lt;A
            NAME&gt;</code> element won't be recognized by some browsers; be
            sure to put at least a word or two inside the
            <code>&lt;A&gt;</code>.
          </li>
          <li>
            Having unadorned text where the validator was expecting a
            sub-element of FOO. For instance, <code>&lt;DL&gt;fake
            indent&lt;/DL&gt;</code> will produce this error, since inside a
            <code>&lt;DL&gt;</code>, the validator only expects to see
            <code>&lt;DT&gt;</code>'s and <code>&lt;DD&gt;</code>'s.
          </li>
          <li>
            A tag of the form <code>&lt;TABLE WIDTH=100%&gt;</code>. The
            previous error should have been that the `%' was <a
            href="#attr-char">"not allowed in attribute specification list"</a>.
            What's happening here is that, in trying to get past the `%', the
            validator has become confused and thinks the `%' is <em>inside</em>
            the <code>&lt;TABLE&gt;...&lt;/TABLE&gt;</code>, thus triggering the
            error message for the previous reason. This error will likely be
            followed by mistaken complaints that your <code>&lt;TR&gt;</code>'s
            are <a href="#not-allowed">"not allowed here"</a>, plus a complaint
            about your <code>&lt;/TABLE&gt;</code> end tag. The solution is to
            put the attribute value in quotes; ie. <code>&lt;TABLE
            WIDTH="100%"&gt;</code>.
          </li>
        </ul>
        <p>
        	In general, you should always explicitly close all elements and
        	quote all attribute values.
        </p>
      </dd>
      <dt><a id="floating-close" name="floating-close">"end tag for element "FOO" which is not open"</a></dt>
      <dd>
        <p>
          The validator found an end tag, represented here by FOO, without a
          corresponding start tag. This frequently occurs in conjunction with
          the <a href="#no-end-tag">previous error</a>. For instance, given
          <code>&lt;B&gt;&lt;I&gt;nope&lt;/B&gt;&lt;/I&gt;</code>, the validator
          will insert a <code>&lt;/I&gt;</code> before the
          <code>&lt;/B&gt;</code>, and then will find the
          <code>&lt;/I&gt;</code> after the <code>&lt;/B&gt;</code> and will
          have nothing to match it with.
        </p>
        <p>
          A subtle variation of this is <code>&lt;P&gt;&lt;H4&gt;fake font
          change&lt;/H4&gt;&lt;/P&gt;</code>. <code>&lt;H4&gt;</code>'s aren't
          allowed inside <code>&lt;P&gt;</code>'s, but since HTML allows you to
          omit the <code>&lt;/P&gt;</code> end tag for paragraphs, the validator
          assumes that you meant <code>&lt;P&gt;&lt;/P&gt;&lt;H4&gt;fake font
          change&lt;/H4&gt;&lt;/P&gt;</code>, in which case the final
          <code>&lt;/P&gt;</code> is indeed superfluous.
        </p>
        <p>
          This error can also be caused by incorrectly supplying an end tag for
          "empty" elements like <code>&lt;HR&gt;</code>, <code>&lt;BR&gt;</code>
          or <code>&lt;IMG&gt;</code>.
        </p>
      </dd>
      <dt><a id="omitted-content" name="omitted-content">"end tag for `FOO' which is not finished"</a></dt>
      <dd>
        <p>
          You have a FOO element, but you have omitted some required sub-element
          of it. For instance, a <code>TABLE</code> with no <code>TR</code>'s
          would cause this error.
        </p>
      </dd>
      <dt><a id="no-start-tag" name="no-start-tag">"start tag for `FOO' omitted, but its declaration does not permit this"</a></dt>
      <dd>
        <p>
          The validator expected you to start a FOO element at the indicated
          point. This probably means you've put unadorned text somewhere it
          isn't allowed; for instance, <code>&lt;UL&gt;fake
          indent&lt;/UL&gt;</code> will cause this error.
        </p>
      </dd>
      <dt><a id="bad-entity" name="bad-entity">"unknown entity `FOO'"</a></dt>
      <dd>
        <p>
          The validator has found an entity (something like
          <code>&amp;this;</code>) that it doesn't recognize. There are a few
          possibilities:
        </p>
        <ul>
          <li>
            <p>
	      A reference to a URI that uses <code>&amp;</code> as a separator
	      between parameters, such as
	      "<code>http://example.org/prog?x=1&amp;y=2</code>".
	    </p>
            <p>
	      To solve this problem, simply replace all the <code>&amp;</code>'s
	      in attribute values with <code>&amp;amp;</code> (user agents will
	      convert them back before following the links.)
            </p>
	    <p>
              Another way to get around this problem is for the author of the CGI
	      program to allow a different value to be used between arguments,
              like ';' or '|', which would allow the link to be coded as e.g.
              <code>&lt;a href="http://example.org/prog?x=1;y=2"&gt;</code>
            </p>
          </li>
          <li>
            An unterminated entity; for instance, <code>this&amp;ampthat</code>
            for "this&amp;that", which the validator (correctly) interprets as a
            request for the entity <code>&amp;ampthat;</code>. Technically, any
            non-alphanumeric character (such as a space) will suffice to
            terminate the entity, but some browsers get this wrong; the safest
            thing to do is to terminate all entities with a semicolon, turning
            our example into <code>this&amp;amp;that</code>.
          </li>
          <li>
            The entity <code>&amp;quot;</code> in conjunction with the HTML 3.2
            <code>DOCTYPE</code>. This entity was <a
            href="http://lists.w3.org/Archives/Public/www-html/1997Mar/0003.html">accidentally
            omitted</a> from the most recent version of the HTML 3.2 DTD. You
            should be able to ignore this error safely, though if you wish, you
            can replace <code>&amp;quot;</code> with the equivalent character
            entity <code>&amp;#34;</code>.
          </li>
        </ul>
      </dd>
      <dt><a id="bad-char" name="bad-char">"non SGML character number ###"</a></dt>
      <dd>
        <p>
          You've used an illegal character in your text. HTML uses the standard
          ISO8859-1 character encoding, and ISO8859-1 leaves undefined 65
          character codes (0 to 31 inclusive and 127 to 159 inclusive); the
          validator has found one of these undefined characters in your
          document. The character may appear on your browser as a curly quote,
          or a trademark symbol, or some other fancy glyph; on a different
          computer, however, it will likely appear as a completely different
          character, or nothing at all.
        </p>
        <p>
          Your best bet is to replace the character with the nearest equivalent
          ASCII character, or to use an appropriate <a
          href="http://www.w3.org/hypertext/WWW/MarkUp/html3/latin1.html">character
          entity</a>. For more information on ISO8859-1, see <a
          href="http://ppewww.ph.gla.ac.uk/%7Eflavell/aflavell.html">Alan
          Flavell</a>'s excellent <a
          href="http://ppewww.ph.gla.ac.uk/%7Eflavell/iso8859/">ISO8859-1/HTML
          reference</a>.
        </p>
        <p>
          This error can also be triggered by formatting characters embedded in
          documents by some word processors. If you use a word processor to edit
          your HTML documents, be sure to use the "Save as ASCII" or similar
          command to save the document without formatting information.
        </p>
      </dd>
      <dt><a id="unicode-char" name="unicode-char">"`####' is not a valid character number"</a></dt>
      <dd>
        <p>
          You'll get several occurrences of this error if you use the Cougar
          DTD. Cougar uses the 16-bit UCS-4 (a.k.a. "Unicode") character set
          instead of the 8-bit ISO8859-1 character set used by HTML 2.0 and HTML
          3.2. It also defines mnemonic entities for various Unicode characters;
          for instance, the entity <code>&amp;trade;</code> is defined as the
          character entity <code>&amp;#8482;</code>, which is the Unicode
          trademark character. Unfortunately, the <code>nsgmls</code> executable
          used by the validator does not appear to have 16-bit character support
          compiled in, and so it chokes on these 16-bit character entities.
        </p>
        <p>
          These errors are not produced by anything in your document and should
          not otherwise affect the validation of your document, so you can
          pretty much ignore them.
        </p>
      </dd>
      <dt><a id="bad-pub-id" name="bad-pub-id">"cannot generate system identifier for entity `HTML'"</a></dt>
      <dd>
        <p>
          Your <code>DOCTYPE</code> declaration contains a public identifier
          that the validator doesn't recognize. See the <a
          href="sgml.html#doctype">discussion of <code>DOCTYPE</code></a> for an
          explanation of what's happening, and what public identifiers the
          validator recognizes.
        </p>
        <p>
          Note that all of the rest of the errors you received are meaningless;
          the validator was unable to find a <a href="sgml.html#dtd">DTD</a> to
          work from, and thus could not validate your document.
        </p>
      </dd>
      <dt><a id="missing-subel" name="missing-subel">"missing a required sub-element of `FOO'"</a></dt>
      <dd>
        <p>
          The element "FOO" is defined to <em>require</em> one or more
          sub-elements. One example is TR which requires one or more TD or TH
          elements.
        </p>
      </dd>
      <dt><a id="start-tag" name="start-tag">"start tag was here"</a></dt>
      <dd>
        <p>
          Not an error, but rather a pointer to the start tag of the element
          the previous error referred to.
        </p>
      </dd>
      <dt><a id="utf8-bom" name="utf8-bom">"UTF-8 'BOM' detected and removed"</a></dt>
      <dd>
        <p>
          The document contained an UTF-8 encoded Unicode Byte Order Mark (BOM)
          as the first character and we have removed it before parsing.
          Many XML Processors
          do not allow it. To be on the safe side you should avoid using the
          BOM in UTF-8 encoded documents.
        </p>
        <p>
          Note that the BOM in <em>UTF-16</em> encoded documents
          is required and handled by all conforming XML Processors.
        </p>
      </dd>
    </dl>

<!--#include virtual="/footer.html" -->
  </body>
</html>