mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-27 14:28:56 +00:00
565e478d69
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@334826 c90b9560-bf6c-de11-be94-00142212c4b1
435 lines
11 KiB
XML
435 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
|
|
<!-- $Revision$ -->
|
|
<phpdoc:classref xml:id="class.mongocursorexception" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<title>The MongoCursorException class</title>
|
|
<titleabbrev>MongoCursorException</titleabbrev>
|
|
|
|
<partintro>
|
|
|
|
<!-- {{{ MongoCursorException intro -->
|
|
<section xml:id="mongocursorexception.intro">
|
|
&reftitle.intro;
|
|
<para>
|
|
Caused by accessing a cursor incorrectly or a error receiving a reply. Note
|
|
that this can be thrown by any database request that receives a reply, not
|
|
just queries. Writes, commands, and any other operation that sends
|
|
information to the database and waits for a response can throw a
|
|
<classname>MongoCursorException</classname>. The only exception is
|
|
<literal>new MongoClient()</literal> (creating a new connection), which will
|
|
only throw <classname>MongoConnectionException</classname>s.
|
|
</para>
|
|
|
|
<para>
|
|
This returns a specific error message to help diagnose the problem and a
|
|
numeric error code associated with the cause of the exception.
|
|
</para>
|
|
|
|
<para>
|
|
For example, suppose you tried to insert two documents with the same _id:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
try {
|
|
$collection->insert(array("_id" => 1), array("w" => 1));
|
|
$collection->insert(array("_id" => 1), array("w" => 1));
|
|
}
|
|
catch (MongoCursorException $e) {
|
|
echo "error message: ".$e->getMessage()."\n";
|
|
echo "error code: ".$e->getCode()."\n";
|
|
}
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
This would produce output like:
|
|
<programlisting role="txt">
|
|
<![CDATA[
|
|
error message: E11000 duplicate key error index: foo.bar.$_id_ dup key: { : 1 }
|
|
error code: 11000
|
|
]]>
|
|
</programlisting>
|
|
Note that the MongoDB error code (11000) is used for the PHP error code. The
|
|
PHP driver uses the "native" error code wherever possible.
|
|
</para>
|
|
|
|
<para>
|
|
The following is a list of common errors, codes, and causes. Exact errors
|
|
are in italics, errors where the message can vary are described in obliques.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>cannot modify cursor after beginning iteration</literal>
|
|
</para>
|
|
<para>
|
|
Code: 0
|
|
</para>
|
|
<para>
|
|
You are calling a method that sets up the query after executing the query.
|
|
Reset the cursor and try again.
|
|
</para>
|
|
<para>
|
|
An example:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
try {
|
|
$cursor = $collection->find();
|
|
var_dump($cursor->getNext());
|
|
|
|
// getNext() queried the database, it's too late to set a limit
|
|
$cursor->limit(1);
|
|
}
|
|
catch (MongoCursorException $e) {
|
|
echo "error message: ".$e->getMessage()."\n";
|
|
echo "error code: ".$e->getCode()."\n";
|
|
}
|
|
|
|
// this will work, though:
|
|
$cursor->getNext();
|
|
$cursor->reset();
|
|
$cursor->limit(1);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Get next batch send errors
|
|
</para>
|
|
<para>
|
|
Code: 1
|
|
</para>
|
|
<para>
|
|
Could not send the query to the database. Make sure the database is
|
|
still up and the network is okay.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>cursor not found</literal>
|
|
</para>
|
|
<para>
|
|
Code: 2
|
|
</para>
|
|
<para>
|
|
The driver was trying to fetch more results from the database, but the
|
|
database did not have a record of the query. This usually means that the
|
|
cursor timed out on the server side: after a few minutes of inactivity,
|
|
the database will kill a cursor (see
|
|
<function>MongoCursor::immortal</function> for information on preventing
|
|
this).
|
|
</para>
|
|
<para>
|
|
An example:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
try {
|
|
$cursor = $collection->find();
|
|
$cursor->getNext();
|
|
|
|
// sleep for 15 minutes
|
|
sleep(60*15);
|
|
|
|
while ($cursor->hasNext()) {
|
|
$cursor->getNext();
|
|
}
|
|
}
|
|
catch (MongoCursorException $e) {
|
|
echo "error message: ".$e->getMessage()."\n";
|
|
echo "error code: ".$e->getCode()."\n";
|
|
}
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>cursor->buf.pos is null</literal>
|
|
</para>
|
|
<para>
|
|
Code: 3
|
|
</para>
|
|
<para>
|
|
This may indicate you are out of RAM or some other extraordinary
|
|
circumstance.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>couldn't get response header</literal>
|
|
</para>
|
|
<para>
|
|
Code: 4
|
|
</para>
|
|
<para>
|
|
A common error if the database or network goes down. This means that the
|
|
driver couldn't get a response from the connection.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>no db response</literal>
|
|
</para>
|
|
<para>
|
|
Code: 5
|
|
</para>
|
|
<para>
|
|
This may not even be an error, for example, the database command
|
|
"shutdown" returns no response. However, if you were expecting a
|
|
response, this means the database didn't give one.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>bad response length: %d, did the db assert?</literal>
|
|
</para>
|
|
<para>
|
|
Code: 6
|
|
</para>
|
|
<para>
|
|
This means that the database said that its response was less than 0. This
|
|
error probably indicates a network error or database corruption.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>incomplete header</literal>
|
|
</para>
|
|
<para>
|
|
Code: 7
|
|
</para>
|
|
<para>
|
|
Highly unusual. Occurs if the database response started out correctly,
|
|
but broke off in the middle. Probably indicates a network problem.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>incomplete response</literal>
|
|
</para>
|
|
<para>
|
|
Code: 8
|
|
</para>
|
|
<para>
|
|
Highly unusual. Occurs if the database response started out correctly,
|
|
but broke off in the middle. Probably indicates a network problem.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>couldn't find a response</literal>
|
|
</para>
|
|
<para>
|
|
Code: 9
|
|
</para>
|
|
<para>
|
|
If the response was cached and now cannot be located.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>error getting socket</literal>
|
|
</para>
|
|
<para>
|
|
Code: 10
|
|
</para>
|
|
<para>
|
|
The socket was closed or encountered an error. The driver should
|
|
automatically reconnect (if possible) on the next operation.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>couldn't find reply, please try again</literal>
|
|
</para>
|
|
<para>
|
|
Code: 11
|
|
</para>
|
|
<para>
|
|
The driver saves any database responses it cannot immediately match with a
|
|
request. This exception occurs if the driver has already passed your
|
|
request's response and cannot find your response in its cache.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>error getting database response: errstr</literal>
|
|
</para>
|
|
<para>
|
|
<literal>WSA error getting database response: errstr</literal>
|
|
</para>
|
|
<para>
|
|
"errstr" is an io error reported directly from the C socket
|
|
subsystem. On Windows, the error message is prefixed with "WSA".
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>Timeout error</literal>
|
|
</para>
|
|
<para>
|
|
Code: 13
|
|
</para>
|
|
<para>
|
|
If there was an error while waiting for a query to complete.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>couldn't send query: <various></literal>
|
|
</para>
|
|
<para>
|
|
Code: 14
|
|
</para>
|
|
<para>
|
|
C socket error on send.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>max number of retries exhausted, couldn't send query</literal>
|
|
</para>
|
|
<para>
|
|
Code: 19
|
|
</para>
|
|
<para>
|
|
The driver will automatically retry "plain" queries (not commands) a
|
|
couple of times if the first attempt failed for certain reasons. This is
|
|
to cause fewer exceptions during replica set failover (although you will
|
|
probably still have to deal with some) and gloss over transient network
|
|
issues.
|
|
</para>
|
|
<para>
|
|
This can also be caused by the driver not being able to reconnect at all
|
|
to the database (if, for example, the database is unreachable).
|
|
</para>
|
|
<para>
|
|
Version 1.2.2+.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>Errors passed through by the database</title>
|
|
<para>
|
|
Database errors should always trigger
|
|
<classname>MongoCursorExceptions</classname> on queries.
|
|
Error messages and codes are sent directly from the database and you should
|
|
be able to see matching errors in the database log.
|
|
</para>
|
|
|
|
<para>
|
|
A few common database errors are listed below:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>E11000 duplicate key error index: foo.bar.$X dup key: { /* ... */ }</literal>
|
|
</para>
|
|
<para>
|
|
Code: 11000
|
|
</para>
|
|
<para>
|
|
Database error for duplicate keys.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>not master</literal>
|
|
</para>
|
|
<para>
|
|
Codes: 10107, 13435, and 10058
|
|
</para>
|
|
<para>
|
|
Not master errors, piped through by the database. ach of these will
|
|
cause the driver to disconnect and attempt to find a new primary. The
|
|
actual error you get on failover may not be a "not master" error,
|
|
depending on when the change in primary occurs.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</section>
|
|
<!-- }}} -->
|
|
|
|
<section xml:id="mongocursorexception.synopsis">
|
|
&reftitle.classsynopsis;
|
|
|
|
<!-- {{{ Synopsis -->
|
|
<classsynopsis>
|
|
<ooclass><classname>MongoCursorException</classname></ooclass>
|
|
|
|
<!-- {{{ Class synopsis -->
|
|
<classsynopsisinfo>
|
|
<ooclass>
|
|
<classname>MongoCursorException</classname>
|
|
</ooclass>
|
|
<ooclass>
|
|
<modifier>extends</modifier>
|
|
<classname>MongoException</classname>
|
|
</ooclass>
|
|
</classsynopsisinfo>
|
|
<!-- }}} -->
|
|
|
|
</classsynopsis>
|
|
<!-- }}} -->
|
|
|
|
</section>
|
|
|
|
</partintro>
|
|
|
|
&reference.mongo.entities.mongocursorexception;
|
|
|
|
</phpdoc:classref>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|