Skip to content


This topic lists the frequently asked questions for using NebulaGraph 3.1.0. You can use the search box in the help center or the search function of the browser to match the questions you are looking for.

If the solutions described in this topic cannot solve your problems, ask for help on the NebulaGraph forum or submit an issue on GitHub issue.

About manual updates

"Why is the behavior in the manual not consistent with the system?"

NebulaGraph is still under development. Its behavior changes from time to time. Users can submit an issue to inform the team if the manual and the system are not consistent.


If you find some errors in this topic:

  1. Click the pencil button at the top right side of this page.
  2. Use markdown to fix this error. Then click "Commit changes" at the bottom, which will start a Github pull request.
  3. Sign the CLA. This pull request will be merged after the acceptance of at least two reviewers.

About legacy version compatibility

X version compatibility

Neubla Graph 3.1.0 is not compatible with NebulaGraph 1.x nor 2.0-RC in both data formats and RPC-protocols, and vice versa. The service process may quit if using an lower version client to connect to a higher version server.

To upgrade data formats, see Upgrade NebulaGraph to the current version. Users must upgrade all clients.

About execution errors

"How to resolve the error SemanticError: Missing yield clause.?"

Starting with NebulaGraph 3.0.0, the statements LOOKUP, GO, and FETCH must output results with the YIELD clause. For more information, see YIELD.

"How to resolve the error Host not enough!?"

From NebulaGraph version 3.0.0, the Storage services added in the configuration files CANNOT be read or written directly. The configuration files only register the Storage services into the Meta services. You must run the ADD HOSTS command to read and write data on Storage servers. For more information, see Manage Storage hosts.

"How to resolve the error To get the property of the vertex in 'v.age', should use the format 'var.tag.prop'?"

From NebulaGraph version 3.0.0, patterns support matching multiple tags at the same time, so you need to specify a tag name when querying properties. The original statement RETURN variable_name.property_name is changed to RETURN variable_name.<tag_name>.property_name.

"How to resolve the error Storage Error E_RPC_FAILURE?"

The reason for this error is usually that the storaged process returns too many data back to the graphd process. Possible solutions are as follows:

  • Modify configuration files: Modify the value of --storage_client_timeout_ms in the nebula-graphd.conf file to extend the connection timeout of the Storage client. This configuration is measured in milliseconds (ms). For example, set --storage_client_timeout_ms=60000. If this parameter is not specified in the nebula-graphd.conf file, specify it manually. Tip: Add --local_config=true at the beginning of the configuration file and restart the service.
  • Optimize the query statement: Reduce queries that scan the entire database. No matter whether LIMIT is used to limit the number of returned results, use the GO statement to rewrite the MATCH statement (the former is optimized, while the latter is not).
  • Check whether the Storaged process has OOM. (dmesg |grep nebula).
  • Use better SSD or memory for the Storage Server.
  • Retry.

"How to resolve the error The leader has changed. Try again later?"

It is a known issue. Just retry 1 to N times, where N is the partition number. The reason is that the meta client needs some heartbeats to update or errors to trigger the new leader information.

Unable to download SNAPSHOT packages when compiling Exchange, Connectors, or Algorithm

Problem description: The system reports Could not find artifact com.vesoft:client:jar:xxx-SNAPSHOT when compiling.

Cause: There is no local Maven repository for storing or downloading SNAPSHOT packages. The default central repository in Maven only stores official releases, not development versions (SNAPSHOTs).

Solution: Add the following configuration in the profiles scope of Maven's setting.xml file:


"How to resolve [ERROR (-1004)]: SyntaxError: syntax error near?"

In most cases, a query statement requires a YIELD or a RETURN. Check your query statement to see if YIELD or RETURN is provided.

"How to resolve the error can’t solve the start vids from the sentence?"

The graphd process requires start vids to begin a graph traversal. The start vids can be specified by the user. For example:

> GO FROM ${vids} ...
> MATCH (src) WHERE id(src) == ${vids}
# The "start vids" are explicitly given by ${vids}.

It can also be found from a property index. For example:

# CREATE TAG INDEX IF NOT EXISTS i_player ON player(name(20));

> LOOKUP ON player WHERE == "abc" | ... YIELD ...
> MATCH (src) WHERE == "abc" ...
# The "start vids" are found from the property index "name".

Otherwise, an error like can’t solve the start vids from the sentence will be returned.

"How to resolve the error Wrong vertex id type: 1001?"

Check whether the VID is INT64 or FIXED_STRING(N) set by create space. For more information, see create space.

"How to resolve the error The VID must be a 64-bit integer or a string fitting space vertex id length limit.?"

Check whether the length of the VID exceeds the limitation. For more information, see create space.

"How to resolve the error edge conflict or vertex conflict?"

NebulaGraph may return such errors when the Storage service receives multiple requests to insert or update the same vertex or edge within milliseconds. Try the failed requests again later.

"How to resolve the error RPC failure in MetaClient: Connection refused?"

The reason for this error is usually that the metad service status is unusual, or the network of the machine where the metad and graphd services are located is disconnected. Possible solutions are as follows:

  • Check the metad service status on the server where the metad is located. If the service status is unusual, restart the metad service.
  • Use telnet meta-ip:port to check the network status under the server that returns an error.
  • Check the port information in the configuration file. If the port is different from the one used when connecting, use the port in the configuration file or modify the configuration.

"How to resolve the error StorageClientBase.inl:214] Request to "x.x.x.x":9779 failed: N6apache6thrift9transport19TTransportExceptionE: Timed Out in nebula-graph.INFO?"

The reason for this error may be that the amount of data to be queried is too large, and the storaged process has timed out. Possible solutions are as follows:

  • When importing data, set Compaction manually to make read faster.
  • Extend the RPC connection timeout of the Graph service and the Storage service. Modify the value of --storage_client_timeout_ms in the nebula-storaged.conf file. This configuration is measured in milliseconds (ms). The default value is 60000ms.

"How to resolve the error MetaClient.cpp:65] Heartbeat failed, status:Wrong cluster! in nebula-storaged.INFO, or HBProcessor.cpp:54] Reject wrong cluster host "x.x.x.x":9771! in nebula-metad.INFO?

The reason for this error may be that the user has modified the IP or the port information of the metad process, or the storage service has joined other clusters before. Possible solutions are as follows:

Delete the file in the installation directory where the storage machine is deployed (the default installation directory is /usr/local/nebula), and restart the storaged service.

About design and functions

"How is the time spent value at the end of each return message calculated?"

Take the returned message of SHOW SPACES as an example:

nebula> SHOW SPACES;
| Name               |
| "basketballplayer" |
Got 1 rows (time spent 1235/1934 us)
  • The first number 1235 shows the time spent by the database itself, that is, the time it takes for the query engine to receive a query from the client, fetch the data from the storage server, and perform a series of calculations.
  • The second number 1934 shows the time spent from the client's perspective, that is, the time it takes for the client from sending a request, receiving a response, and displaying the result on the screen.

Why does the port number of the nebula-storaged process keep showing red after connecting to NebulaGraph?

Because the nebula-storaged process waits for nebula-metad to add the current Storage service during the startup process. The Storage works after it receives the ready signal. Starting from NebulaGraph 3.0.0, the Meta service cannot directly read or write data in the Storage service that you add in the configuration file. The configuration file only registers the Storage service to the Meta service. You must run the ADD HOSTS command to enable the Meta to read and write data in the Storage service. For more information, see Manage Storage hosts.

Why is there no line separating each row in the returned result of NebulaGraph 2.6.0?

This is caused by the release of Nebula Console 2.6.0, not the change of NebulaGraph core. And it will not affect the content of the returned data itself.

About dangling edges

A dangling edge is an edge that only connects to a single vertex and only one part of the edge connects to the vertex.

Dangling edges may appear in NebulaGraph 3.1.0 as the design. And there is no MERGE statements of openCypher. The guarantee for dangling edges depends entirely on the application level. For more information, see INSERT VERTEX, DELETE VERTEX, INSERT EDGE, DELETE EDGE.

"Can I set replica_factor as an even number in CREATE SPACE statements, e.g., replica_factor = 2?"


The Storage service guarantees its availability based on the Raft consensus protocol. The number of failed replicas must not exceed half of the total replica number.

When the number of machines is 1, replica_factor can only be set to1.

When there are enough machines and replica_factor=2, if one replica fails, the Storage service fails. No matter replica_factor=3 or replica_factor=4, if more than one replica fails, the Storage Service fails. To prevent unnecessary waste of resources, we recommend that you set an odd replica number.

We suggest that you set replica_factor=3 for a production environment and replica_factor=1 for a test environment. Do not use an even number.

"Is stopping or killing slow queries supported?"

Yes. For more information, see Kill query.

"Why are the query results different when using GO and MATCH to execute the same semantic query?"

The possible reasons are listed as follows.

  • GO statements find the dangling edges.
  • RETURN commands do not specify the sequence.
  • The dense vertex truncation limitation defined by max_edge_returned_per_vertex in the Storage service is triggered.
  • Using different types of paths may cause different query results.

    • GO statements use walk. Both vertices and edges can be repeatedly visited in graph traversal.
    • MATCH statements are compatible with openCypher and use trail. Only vertices can be repeatedly visited in graph traversal.

The example is as follows.


All queries that start from A with 5 hops will end at C (A->B->C->D->E->C). If it is 6 hops, the GO statement will end at D (A->B->C->D->E->C->D), because the edge C->D can be visited repeatedly. However, the MATCH statement returns empty, because edges cannot be visited repeatedly.

Therefore, using GO and MATCH to execute the same semantic query may cause different query results.

For more information, see Wikipedia.

"How to count the vertices/edges number of each tag/edge type?"

See show-stats.

"How to get all the vertices/edge of each tag/edge type?"

  1. Create and rebuild the index.

    > CREATE TAG INDEX IF NOT EXISTS i_player ON player();
  2. Use LOOKUP or MATCH. For example:

    > LOOKUP ON player;
    > MATCH (n:player) RETURN n;

For more information, see INDEX, LOOKUP, and MATCH.

"How to get all the vertices/edges without specifying the types?"

By nGQL, you CAN NOT directly getting all the vertices without specifying the tags, neither the edges, or you can use the LIMIT clause to limit the number of returns.

E.g., You CAN NOT run MATCH (n) RETURN (n). An error like Scan vertices or edges need to specify a limit number, or limit number can not push down. will be returned.

You can use Nebula Algorithm.

Or get vertices by each tag, and then group them by yourself.

Can non-English characters be used as identifiers, such as the names of graph spaces, tags, edge types, properties, and indexes?

Yes, for more information, see Keywords and reserved words.

"How to get the out-degree/the in-degree of a vertex with a given name"?

The out-degree of a vertex refers to the number of edges starting from that vertex, while the in-degree refers to the number of edges pointing to that vertex.

nebula > MATCH (s)-[e]->() WHERE id(s) == "given" RETURN count(e); #Out-degree
nebula > MATCH (s)<-[e]-() WHERE id(s) == "given" RETURN count(e); #In-degree

This is a very slow operation to get the out/in degree since no accelaration can be applied (no indices or caches). It also could be out-of-memory when hitting a supper-node.

"How to quickly get the out-degree and in-degree of all vertices?"

There is no such command.

You can use Nebula Algorithm.

About operation and maintenance

"The runtime log files are too large. How to recycle the logs?"

By default, the runtime logs of NebulaGraph are stored in /usr/local/nebula/logs/. The INFO level log files are nebula-graphd.INFO, nebula-storaged.INFO, nebula-metad.INFO. If an alarm or error occurs, the suffixes are modified as .WARNING or .ERROR.

NebulaGraph uses glog to print logs. glog cannot recycle the outdated files. To rotate logs, you can:

"How to check the NebulaGraph version?"

If the service is running: run command SHOW HOSTS META in nebula-console. See SHOW HOSTS.

If the service is not running:

Different installation methods make the method of checking the version different. The instructions are as follows:

If the service is not running, run the command ./<binary_name> --version to get the version and the Git commit IDs of the NebulaGraph binary files. For example:

$ ./nebula-graphd --version
  • If you deploy NebulaGraph with Docker Compose

    Check the version of NebulaGraph deployed by Docker Compose. The method is similar to the previous method, except that you have to enter the container first. The commands are as follows:

    docker exec -it nebula-docker-compose_graphd_1 bash
    cd bin/
    ./nebula-graphd --version
  • If you install NebulaGraph with RPM/DEB package

    Run rpm -qa |grep nebula to check the version of NebulaGraph.

"How to scale out or scale in? (Enterprise Edition only)"

NebulaGraph 3.1.0 does not provide any commands to support automatic scale out/in. You can refer to the following steps:

  1. Scale out and scale in metad: The metad process can not be scaled out or scale in. The process cannot be moved to a new machine. You cannot add a new metad process to the service.


    You can use the Meta transfer script tool to migrate Meta services. Note that the Meta-related settings in the configuration files of Storage and Graph services need to be modified correspondingly.

  2. Scale in graphd: Remove the IP of the graphd process from the code in the client. Close this graphd process.

  3. Scale out graphd: Prepare the binary and config files of the graphd process in the new host. Modify the config files and add all existing addresses of the metad processes. Then start the new graphd process.

  4. Scale in storaged: See Balance remove command. After the command is finished, stop this storaged process.

  5. Scale out storaged: Prepare the binary and config files of the storaged process in the new host, Modify the config files and add all existing addresses of the metad processes. Then register the storaged process to the metad, and then start the new storaged process. For details, see Register storaged services.

You also need to run Balance Data and Balance leader after scaling in/out storaged.

"After changing the name of the host, the old one keeps displaying OFFLINE. What should I do?"

Hosts with the status of OFFLINE will be automatically deleted after one day.

About connections

"Which ports should be opened on the firewalls?"

If you have not modified the predefined ports in the Configurations, open the following ports for the NebulaGraph services:

Service Port
Meta 9559, 9560, 19559, 19560
Graph 9669, 19669, 19670
Storage 9777 ~ 9780, 19779, 19780

If you have customized the configuration files and changed the predefined ports, find the port numbers in your configuration files and open them on the firewalls.

For those eco-tools, see the corresponding document.

"How to test whether a port is open or closed?"

You can use telnet as follows to check for port status.

telnet <ip> <port>


If you cannot use the telnet command, check if telnet is installed or enabled on your host.

For example:

// If the port is open:
$ telnet 9669
Connected to
Escape character is '^]'.

// If the port is closed or blocked:
$ telnet 9777
telnet: connect to address Connection refused

About license

Are the Dashboard/Explorer/NebulaGraph Enterprise Edition licenses the same?

No, the licenses of Dashboard, Explorer, and NebulaGraph Enterprise Editions are independent of each other and cannot be used interchangeably.

During the validity period of the NebulaGraph Enterprise Edition license, after replacing the enterprise edition Meta with the community edition Meta, can the community edition Meta be used with the enterprise edition Graph and Storage?

No, mixed deployments of the enterprise edition services and the community edition services are not supported.

After the NebulaGraph Enterprise Edition license expires, is it possible that copy the data in the data directory and paste it to the same directory of NebulaGraph Community Edition, and then use NebulaGraph services as normal?

Yes, it is possible. The data of the Enterprise Edition can be used in the Community Edition. The pasted data will only work properly in the services deployed in the Community Edition. Mixed deployments of the enterprise edition services and the community edition services are not supported. For example, the mixed deployment of the enterprise edition Meta service and the community edition Graph and Storage services is not supported.

Is there any message before the license expires, and how to renew the license after it expires?

The system will send expiration notifications before the license expires.

The notification time before the license expires is different for the full version license and the trial version license.

  • For the full version license:

    • Within 30 days before the license expires or on the day the license expires, there is an expiration reminder when NebulaGraph/Dashboard/Explorer is started.
    • There is a 14-day buffer period after expiration. During the buffer period, you will receive expiration notifications and can continue using NebulaGraph/Dashboard/Explorer. After the buffer period ends, the corresponding service will be down and cannot be started.
  • For the trial version license:

    • Within 7 days before the license expires or on the day the license expires, there is an expiration reminder when NebulaGraph/Dashboard/Explorer is started.
    • There is no buffer period after expiration. Once the license expires, the corresponding service will be down and cannot be started.

After your license expires, contact us via to renew it.

Last update: March 13, 2023